Screen Programming in AmigaOS 4

Submitted by trixie on

  • up
    34%
  • down
    66%


1. Introduction

Under AmigaOS, a program window is always open on a screen. The operating system’s graphic environment can use multiple screens at the same time, providing a number of “virtual desktops” for you to work on. Screens may vary in size (resolution), colour depth, and they can also be mouse-dragged to reveal other screens hiding behind. Amiga programs can use their own, private (called “custom”) screens; they can open a “public” screen to share display with other programs; or they can open no screen at all and instead use another program’s public screen as visitors. Quite naturally, the most popular and most visited public screen is the Workbench.

Amigans have always been very proud of their screen system. It’s a well-established concept that hasn’t changed much throughout the years, unlike other parts of Intuition. Yet from a programmer’s point of view, screens have been redefined in AmigaOS Release 4. Well, not the screens per se – it’s the philosophy of their use that has changed. The following article helps understand the current mindset and explains certain new implications for screen programming and usage.

2. Past to present

In the past, Amiga programs made a heavy use of custom screens. As the resolution of the computer display was low – the typical screen resolution of the time was mere 640x256 pixels – one could quickly lose overview when having too many programs on the Workbench. It was, therefore, normal that individual programs opened their own screens, through which the user switched as needed. To that end software developers often provided screen configuration as part of their programs’ settings.

But now that AmigaOS-compatible computers use high-resolution displays with 16- or 32-bit depth, custom screens have become less useful than before. Why is that? Well, there are now a number of convincing reasons to open programs on the Workbench by default (especially if their GUI consists of a single window). First of all, a large Workbench can comfortably accommodate most programs you typically run during your computing session. Plus, the race for space on the Workbench has become less of an issue with the emergence of modern applications that are able to collapse (“iconify”) their windows to occupy next to no space on the screen. Moreover, running programs on the Workbench brings the benefit of accessibility: you do not need to swap screens to access other programs, disks or the handy features of OS4’s docking utility, AmiDock. Last but not least, using multiple large screens can really be taxing resource-wise. On some lower-end systems you may quickly run out of graphic memory and bring the OS to a crawl just because a couple of programs decided to open their own screen. Sharing a common public screen – such as the Workbench – is more economical.

3. Screens in AmigaOS 4.x

The decline in the importance of custom screens (brought about by hardware innovations) has further been accelerated by two new AmigaOS features that, instead, encourage the use of public screens:

3.1 Automatic public screens
AmigaOS 4.x received a new Preferences editor, Screens, which unfortunately seems to have been escaping the attention of many. The editor allows users to pre-define their own set of named public screens to utilize throughout the system. They are virtual, “automatic screens”: they exist as screen definitions known to Intuition, and are only opened when a program requires them. Let’s say you have a screen called “MyPublicScreen” pre-defined in the Screens editor, as the image below shows:

IMAGE(http://www.perplex.cz/download/os4coding/Screens.jpg)

Now if you provide the following tag in your window creation code

  1. ...
  2. WA_PubScreenName, “MyPublicScreen”,
  3. ...

the screen will be created and opened by Intuition automatically at program startup and the program’s GUI will open on the said screen. When the program closes its last window, Intuition will close and dispose of the screen. Again, automatically. (NOTE: For this to work the pre-defined screen must have “Open/close automatically” ticked in the Screens preferences editor – see the picture above.)

3.2 Greater window mobility
Using a new feature in Window Class (introduced in AmigaOS 4.1 Update 3), ReAction-based programs can now “jump” between screens freely during their runtime. This can greatly increase the usability of certain types of program (such as a calculator, a notepad or a dictionary) because they can be pushed to where they are currently needed, without having to reconfigure and restart the program.

However, screen jumping only works with public screens because custom screens cannot take visitor windows. Once again this shows that custom screens have become a thing of the past.

4. Programming implications

4.1 Use automatic public screens if you can
As it was mentioned above, screens can exist as virtual entities defined externally in the Screens preferences editor. Their creation and disposal is automatically handled by Intuition so no GUI code is required whatsoever. Of course you can still use OpenScreenTags() but why bother and do things the complicated way? Opening an automatic public screen by simply using its name is so much easier! (However, see below for Recommended practice.)

4.2 Screen configuration GUI
This also means that the screen configuration GUI, as we know it from older Amiga programs, will change. Options to open on a custom screen will be gone because custom screens are not practical anymore (see above). Public screen settings will shrink to a single string gadget for the screen name. Screens will be defined externally according to individual user needs. The screenmode-selection gadget and requester will be used rarely in program GUIs.

4.3 Iconification caveats
Older documentation mentioned that a screen can never get closed while there is a program window opened on it: the window works as a screen lock. Although this is perfectly true, some programmers misinterpreted it as “the screen pointer will be valid until your program exits”. Such an assumption no longer works for programs that can iconify their windows – which effectively means most programs of today.

It is not, and never has been, guaranteed that when the user decides to uniconify your program, its original public screen will still be available! Therefore, it is unwise to hold any pointers related to the original screen and/or its properties, such as VisualInfo, rastport, AmigaGuide context etc. If you ever need to keep them, NULL them all at iconify time – you'll obtain them again later. Before the uniconification takes place, first ensure that there is a place for the program to return: LockPubScreen() is a good thing to do. If your program normally opens on a named public screen, provide a Workbench fallback should the lock fail:

  1. if ( !(pubScreen = IIntuition->LockPubScreen("AnyName")) ) pubScreen = IIntuition->LockPubScreen(NULL);
  2. if (pubScreen)
  3.  {
  4.   /* you can safely reopen your window now */
  5.  }

Once you have the new screen pointer, get all other screen-related pointers if your program needs them. If menus are attached using GadTools Library functions, make sure to obtain a new VisualInfo for the screen you'll reopen on, and relayout the menu strip: otherwise the program will crash if it returns to a different screen. When the window is back on, call UnlockPubScreen() and drop the screen lock. Holding locks throughout program runtime might jeopardise the use of automatic public screens.

4.4 Screen jumping caveats
To use the screen-jumping feature (see 3.2 above) successfully, you must understand how this feature works and what Window Class does internally. It performs the necessary housekeeping associated with screen change but it doesn't do everything for you. When the user decides to move the program to another screen and selects the screen name from the pop-up menu, WindowClass updates the program window's WA_PubScreen to point to the new screen, and then sends a WMHI_JUMPSCREEN message. It is fully up to the programmer to react upon this message and reopen the window on the new screen, obtaining or updating all relevant pointers in the process.

Be careful if your program uses sub-windows: whether you create them on-the-fly or at program startup, before opening you must always provide them with a WA_PubScreen tag containing the current screen pointer, otherwise the sub-window could end up on a different screen than the main program window. When travelling between places, do not leave your children behind.

Similarly, if your program uses the AmigaGuide Library to provide online help, remember that when the help system is set up, you receive a pointer to something called the “AmigaGuide context”. The context serves as a handle to your AmigaGuide file, and by design is tied to a particular screen on which the file will open when called for. By now it should be quite clear that if the program is designed to allow jumping between screens, the context for the help system must be re-established each time the screen is changed - otherwise the help file will open behind the current screen, which is not what the user expects.

4.5 Screen properties
If you need to know about a particular screen's properties (such as public screen name, font pointer etc.), use OS4's new function GetScreenAttr() – or GetScreenAttrs() if you want to query about several attributes in one go. Never peek in IntuitionBase or any other system structures.

However, refer to the respective autodocs and study the functions' parameters first! GetScreenAttr() and GetScreenAttrs() are not BOOPSI functions because screens cannot be created as objects. Therefore, although the names seem comfortingly similar to BOOPSI's GetAttr() and GetAttrs(), the obtained attribute values are stored rather differently.

5. Recommended practice

All of these things boil down to a couple of recommendations or guidelines to follow in your GUI programming under AmigaOS Release 4:

  • If your program uses a simple GUI, always open on the Workbench by default.
  • If you want to give users the option to open on a separate screen, let them define the screen parameters themselves using AmigaOS's Screens editor. In your program’s Settings, provide a string gadget for the public screen name. Alternatively, if your program has no Settings section in the GUI and uses Application Library’s XML-based preferences format, provide a key named “Public Screen” (or similar) for the users to enter the screen name. They can easily edit the prefs file with a text editor or the dedicated PrefsObjectsEditor located in the system's Utilities drawer.
  • If your program must use a dedicated screen by default (typically: programs that open many sub-windows), open a public screen via OpenScreenTags(). In your program’s Settings, provide a standard screenmode selector and a checkbox option letting the user to clone the Workbench screen parameters (you’ll do this by passing “SA_LikeWorkbench, TRUE” in the OpenScreenTags() call). Make Clone Workbench the default setting.
  • Remember that automatic public screens created through the Screens prefs editor are user-defined. As such, the program(mer) can never quite rely on their parameters. For example, if you write a program that runs on an automatic screen called "MyProgScreen", this screen will likely be defined differently on individual users' systems. So if your program requires a screen of a certain depth, size etc. to function properly, you should open the screen yourself and not rely on the Screens editor.
  • Do not use custom screens unless you absolutely have to. Expect that the user will want to open various programs on your screen.
  • Do not keep public screens locked throughout program runtime. Call UnlockPubScreen() when your program window (re)opens.
  • Be smart and careful in your code that handles window iconification and uniconification. Never assume that your program’s window will reopen on the same screen. Do not keep any global pointers or locks that refer to the original screen or its properties.
  • Now that windows can jump freely to different screens, caching screen pointers does not make any sense. It never did, actually. Always query the window object using GetAttr() when you need the current screen pointer.
  • Use Intuition's GetScreenAttr() or GetScreenAttrs() to find out about screen properties.

Tags: 

Blog post type: 

Comments

Belxjander's picture

Submitted by Belxjander on

Excellent!... I look forward to making use of this myself,
Glad to know this sort of functionality has become integrated in the new OS release
I remember using KCommodity on Amiga OS 3.x in a limited fashion for this and some other screen promoting

JosDuchIt's picture

Submitted by JosDuchIt on

Very interesting &readable

If you want to give users the option to open on a separate screen, let them define the screen parameters themselves using AmigaOS's Screens editor.

Maybe providing the launch of the Screens editor from your app?
In your program’s Settings, provide a string gadget for the public screen name.

I guess instead, once created , you might as well give the user the opportunity to select it directly from a list of defined public screens? (so as not having to copy the name)
Is this easy to implement ?

trixie's picture

Submitted by trixie on

Maybe providing the launch of the Screens editor from your app?

Yes, the OS development will most likely go in this direction. As the Screens editor doc specifically says, "For the near future, it is envisioned that any application will be able to register its screen's name with the system, and also to invoke the Screens editor (through an API call) and present it to the user as the standard means to configure all aspects of its screen's user interface." (See SYS:Documentation/Prefs/Screens.doc). Before that happens I would stay away from custom kludges trying to invoke the editor.

you might as well give the user the opportunity to select it directly from a list of defined public screens?

I can imagine a string gadget followed by a chooser listing the available public screens (not the ones currently opened but those defined in the Screens editor). Once the OS provides a way to obtain such a list.

As you can see, certain aspects of screen handling are still somewhat uncooked. I'll happily update the article when things become set in stone.

AmigaOne X5000-020 / 2GB RAM / Sapphire Pulse Radeon RX 560 / AmigaOS 4.1 Final Edition Update 2

cha05e90's picture

Submitted by cha05e90 on

Very nice read - thank you very much for this guide!

X1000|II/G4|440ep|2000/060|2000/040|1000

BillEaves's picture

Submitted by BillEaves on

An interesting read.

I found the following intruiging.

3.2 Greater window mobility
Using a new feature in Window Class (introduced in AmigaOS 4.1 Update 3), ReAction-based programs can now “jump” between screens freely during their runtime.

How do you achieve this ?
In MUI you have icons in the window bar that can jump your application to a public screen, but I see no such icons in any apps using Reaction windows.

Or does the ability have to be hard coded by the developer of the application ?

I am interested in this because the new shell can do everything that KingCon could apart from being able to jump onto another screen.

trixie's picture

Submitted by trixie on

@BillEaves

The developer decides whether his/her program will support screen jumping, by passing two specific tags at window creation time. Read Rigo's tutorial that relates to this new feature:

http://www.os4coding.net/blog/rigo/boopsi-windowclass-and-new-popup-menu-functionality-part-one

AmigaOne X5000-020 / 2GB RAM / Sapphire Pulse Radeon RX 560 / AmigaOS 4.1 Final Edition Update 2

trixie's picture

Submitted by trixie on

A small update - added section 4.4 (Screen jumping caveats)

AmigaOne X5000-020 / 2GB RAM / Sapphire Pulse Radeon RX 560 / AmigaOS 4.1 Final Edition Update 2

Massi's picture

Submitted by Massi on

Very clear reading, precious work as usual! Thanks