Categories
Articles

Raising the (tool)bar

When AmigaOS 3.5 was released back in 1999, one of the things I welcomed as an enhancement was the new ReAction GUI toolkit. Although in actuality it was little more than a rebadged third-party product originally called ClassAct, its inclusion as an official part of the operating system made all the difference. Commodore’s object-oriented GUI framework (BOOPSI) had been in place for years but before ReAction came, the framework lacked a comprehensive toolkit to provide elements needed for modern GUI programming.

The accompanying Developer CD V2.1, released in the wake of the updated OS, contained enough documentation and examples for the programmer to start using the new toolkit. Combined with the fact that BOOPSI in general is quite straightforward to use, ReAction was adopted relatively quickly on post-OS3.5 systems including AmigaOS 4.x, where it represents the default GUI toolkit.

However, there are certain things in ReAction that reveal its 1990s mindset and that, with the benefit of hindsight, cannot exactly be called good design choices. For example, some of the gadget classes are a bit quirky to set up and use because they require the programmer to first allocate and populate an Exec list, and then use dedicated functions provided by the class to manipulate the gadget object. This is neither clever (low-level stuff such as lists is imposed on a high-level API) nor needed (the existing set of Intuition’s BOOPSI-related functions is good enough to manipulate any type of object, regardless of complexity). So when we started developing what later became known as the Enhancer Core Classes, we decided to stand clear of the old practice.

The recently released ToolBar Gadget (an enhanced alternative to the system’s SpeedBar Gadget) shows that even a complex BOOPSI class can be implemented with maximum ease of use and programmer comfort in mind. The entire gadget can be set up in a single NewObject() call, i.e. at object-creation time, or freely (re)configured later via Intuition’s setter functions: SetAttrs(), SetGadgetAttrs() or RefreshSetGadgetAttrs(). No need to mess with Exec lists, nodes, or special-purpose functions.

As a warm-up exercise, let’s create a very simple toolbar which only uses text instead of graphic buttons. The gadget set-up code pretty much boils down to the following:

Object *toolbar;

CONST_STRPTR button_labels[] = {"New", "Open", "Save", NULL};

toolbar = IIntuition->NewObject(ToolBarClass, NULL,
          GA_RelVerify, TRUE,
          TOOLBAR_LabelArray, button_labels,
          TAG_END);

Configuring graphic toolbars requires some additional work of course, but before we show any more example code, let’s first review some fundamental concepts and ideas. In particular, we’ll focus on the things that make the ToolBar Gadget different from the SpeedBar.

Every element that makes up a ToolBar object is called a member. There are currently five types of member:

  • button: a regular press-me-for-action button;
  • toggle: a Boolean (on/off) button;
  • separator: a dividing element;
  • spacer: a spacing element;
  • textbox: a read-only element to display text (V53.4)

The member type is set at object creation time, and cannot be changed. The default type is button.

In the SpeedBar Gadget, an element is referred to by a pointer to an Exec list node. (In other words: the class exposes the actual implementation to the programmer, which I think is wrong.) When you want to modify an element, you use a dedicated function, SetSpeedButtonNodeAttrs(), passing the node pointer as an argument to identify the element.

The ToolBar Gadget, on the other hand, treats its elements (members) strictly as “black boxes”: in accordance with BOOPSI principles, you know nothing about their internals or implementation. All you need is a custom ID to refer to the member. IDs are numbers and, like member types, can only be set at object creation time. When you want to modify a member, you use Intuition’s standard BOOPSI setter functions in which you provide the member ID followed by the attribute(s) you want to set for the given member. Several members – all of them if you want – can be modified at once via a single call, which is something you cannot do with SetSpeedButtonNodeAttrs(). To give you an idea, let’s say we have three toolbar buttons we want to disable in one go:

IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, window, NULL,
            TOOLBAR_SetMember, TBID_NEW,
               TBMEMBER_Disabled, TRUE,
            TOOLBAR_SetMember, TBID_OPEN,
               TBMEMBER_Disabled, TRUE,
            TOOLBAR_SetMember, TBID_SAVE,
               TBMEMBER_Disabled, TRUE,
            TAG_END);

Done! (There’s an even easier way to do this if you use member groups, but let’s not get into too much detail. The class documentation has it all if you are curious.)

Another major area of difference is the way button images are handled. With the SpeedBar, you need to create the image outside of the class (typically, by using the BitMap Image class) and then associate the image pointer with the given speedbar node. The ToolBar offers more comfort in that it can create the image – and rescale it, if needed – for you automatically if you provide the file name of the image source. But more importantly: you do not associate image pointers with ToolBar members directly (like you do with the SpeedBar). Instead, you create an image set (or multiple image sets) in which each image bears a unique ID. So a member is configured for particular imagery via an image ID rather than a direct image pointer. In program code, you’ll typically define the image set(s) before you configure the members, for easier referencing. (But this is just a suggested convention. The class is flexible enough to allow configuring the imagery at a later point should you prefer that.)

toolbar = IIntuition->NewObject(ToolBarClass, NULL,
          GA_ID, GID_TOOLBAR,
          GA_RelVerify, TRUE,

          /* configure the image set */
          TOOLBAR_AddImage, TBID_NEW,
             TBIMAGE_Image, myImagePointer1,
          TOOLBAR_AddImage, TBID_OPEN,
             TBIMAGE_Image, myImagePointer2,
          TOOLBAR_AddImage, TBID_SAVE,
             TBIMAGE_Image, myImagePointer3,

          /* configure the buttons */
          TOOLBAR_AddMember, TBID_NEW,
             TBMEMBER_ImageID, TBID_NEW,
          TOOLBAR_AddMember, TBID_OPEN,
             TBMEMBER_ImageID, TBID_OPEN,
          TOOLBAR_AddMember, TBID_SAVE,
             TBMEMBER_ImageID, TBID_SAVE,
          TAG_END);

A great advantage of this implementation is that multiple image sets can easily be defined for a single toolbar, in order to allow a variant look based on user preference. With the current display technology, AmigaOS4 applications may soon need to support different-sized toolbar image sets to cater for both 4K and lower screen resolutions. The ToolBar Gadget facilitates this task because flipping between the configured image sets is a matter of changing one attribute at the toolbar level. When switching to a new image set the gadget will replace all member images automatically, retrieving them from the set based on the image IDs.

I think this might be good enough for starters. I suggest you first have a look at the source code of the examples that come with the class as part of the Enhancer SDK installation, and then go through the extensive documentation. I’m sure you will find the ToolBar Gadget straightforward to use, and I’m looking forward to seeing it adopted in future AmigaOS4 software!

Categories
Articles

Introducing Enhancer Software Core V1.1

A-EON Technology Ltd has just released the new Core V1.1 edition of the Enhancer Software as a free-of-charge download. You may have read the news and be wondering what is contained in it. In this article we explore this new release and walk through the installation process.

Downloading the software

Enhancer Software Core is a free-of-charge commercial release and is exclusively available from the AmiSphere website. Where can you get it? Please point your browser to www.amisphere.com and you will be presented with the front page.

After many years most OS4 users now have an AmiSphere login account which makes accessing a range of download services much easier. Downloads from the AmiSphere website, Updater tool and AMIStore use one common username and password, the AmiSphere credentials.

If you haven’t yet registered, click the Register link to create your profile.

Equipped with your login details you can then proceed to download the software and explore many other AmiSphere services.

Navigate to the section of the website for the Enhancer Software Core and click the Register and download link. You will be prompted to enter your username and password.

Read through the text and click the Register button to add this software to your account permanently. An email will be sent to you to confirm the registration of this product on your account. You will be pleased to find it now will be enabled in Updater tool and also on AmiSphere website as a direct download.

Clicking the direct link takes you to the download area where the software can be directly downloaded. We have tried to keep this release lean in size at around 23MB.

Installing the software

Fire up your favourite decompression tool. Unarchiving the LHA file will reveal the main directory which will no doubt be familiar with users of other editions of the Enhancer Software:

Main Directory

Enhancer Software directory structure
The SDK files necessary for developing programs with the Enhancer Software

You will notice we had tried to keep the structure of the Enhancer Software in line with other editions for consistency.

In the main directory, click the Install_Enhancer_Software icon to start the installation process.

After clicking Proceed then the Read_Me_First window will pop up. Click the icon in your language and read through the documentation including the Installation Notes before continuing with the installation.

The End User Licence Agreement needs to be reviewed and if you agree to the terms/conditions then click the Agree button.

The Enhancer Software Installation offers to backup and store any older files from previous versions. For you peace of mind this is useful if you wish to revert to previous versions of components.

What colour is your preference? To keep all users happy we have provided a choice of installing icons with a blue or black colour theme. Both sets were kindly created by Mason for the Enhancer Software.

Black or blue ?

There are seven main sections for the installation. This is reduced from the full commercial versions of the Enhancer Software but sufficient to get the “core” files installed to your system.

You can deselect specific sections if you run the installation again and just skip to the section you need to reinstall.

Let’s start with the first section:

If you are wondering, the logfile datatype is used by Updater, Ringhio Notifications and a few other utilities to store logs about errors or events. It is great to organise list of information in a more readable format- ideal for skimming through logs to find a crucial event.

The main gadgets and classes are vital user interface components to running modern software created by A-EON and other Amiga developers. They are growing in scope as development progresses and offering users more advanced features inside applications.

AmiSphereServer and Updater tool are necessary to keep your system files up to date. Running them regulary can ensure that the frequent updates are downloaded from AmiSphere and installed easily and quickly to your system. Very useful – I am sure you would agree!

InfoWindow is an utility that displays information to users. It is based on the InfoWindow Class and is used in an increasing amount of applications. Take a look at the Read_Me_First window for a glimpse of it’s capabilities!

The latest open source Codesets library gets installed to ensure that older dusty versions are not lingering on system partitions.

If you are a developer looking to create a system Library or Device, this process has been made easier with LDCK. It is installed in the C drawer along with other commands which are used such as SystemReboot and RequestChooser.

Your AmiSphere account can be administered by using the AmiSphere Prefs tool including changing your password. Optional personal customisations can be made such as specifying an avatar. Yes, that is right, you can have that boing ball avatar you always wanted!

On successful installation a reboot is required to enable the system files to be loaded. This is automatically handled by the System Reboot utility. There is a count down so be quick and save those vital files before it reaches the time limit…

We will be exploring more of the Enhancer Software Core in coming months including how to build your first programs with it. Many of the developers will be featured in the blog articles and explaining how to get the most out of the classes if you are a developer.

I hope you enjoy both using and developing new software with the latest Enhancer Software Core.

Matthew

Categories
Articles

Welcome!

Sadly 2020 has been a turbulent and challenging year for everyone around the globe. This of course has impacted on our lives personally and to a less important extent to the Amiga community and our hobbies.

Usually at this time of year I would be flying around the globe to attend various Amiga shows with Trevor. These events would be a great time to meet and catch up with users, developers and beta testers face to face.

Every developer and beta tester is different. Developer meetings in person can be a great for getting a genuine instinct on what they enjoy working on most. Happy devs are productive devs.

They also offer a general sounding board for floating ideas for new projects and new directions to take our development roadmap.

Lets hope that the social experience of Amiga meetings, shows and conferences can resume again safely next year.

There has been some recent discussion in the community about users having a “window” into the Amiga Developer team to catch glimpses of what we are working on. I would like to thank you for the feedback and welcome you to this blog which will hopefully draw a lot of the disparate news I publish into one place periodically. This blog will hopefully provide a flavour of the trial, tribulations and successes of developing software for our favourite computer platform.

You will hear more from me on a regular basis but it is planned for various developers in our team to feature with articles in their areas of expertise. I hope you will enjoy reading them and learning more depth about the software we produce.

Matthew