The C64 OS Programmer's Guide is being written
This guide is being written and released and few chapters at a time. If a chapter seems to be empty, or if you click a chapter in the table of contents but it loads up Chapter 1, that's mostly likely because the chapter you've clicked doesn't exist yet.
Discussion of development topics are on-going about what to put in this guide. The discusssions are happening in the C64 OS Community Support Discord server, available to licensed C64 OS users.
C64 OS PROGRAMMER'S GUIDE
Chapter 7: Writing an Application
This chapter begins with an overview of what an Application is, what general features it has and how it is different from a Utility. Then the rest of the chapter is a step-by-step tutorial for how to build an Application that makes use of many core technologies: menu system, screen layers, low-level mouse and keyboard events, a Toolkit-based user interface, shared libraries, KERNAL calls, settings and more.
What is an Application?
A C64 OS Application (an App) is a kind of C64 program, but one that meets a specific set of criteria. An Application is a large-scale program, or collection of programs, that is designed for ordinary users to accomplish some goal.
In C64 OS, there is always one (and only one) Application that is actively running on the CPU at a time. The only exception is during boot up or in the phase when an Application is being quit and the next is being loaded.
Unique traits of an Application- Access to the most amount of memory
- Provides a definition for the menu system
- May provide a custom message for the status bar
- Has an icon
- Has copyright and version metadata
- Has an Application bundle
An Application bundle is a structured set of files contained within a subdirectory. The name of the subdirectory (i.e., the name of the bundle) is the name of the Application. An Application is installed when its bundle is stored in system's applications directory (//os/applications/).
The Application bundle contains all of the App's resources; some are optional, others are required. All of the bundle files, taken together, constitute the whole Application. Some example resources include: the main binary, an optional initial binary, an icon file, a menu definitions file, and an about metadata file. The bundle may also contain many other files, such as custom drivers, runtime loadable components, custom Toolkit classes, images, music, text files, help content, and more.
The bundle is where the Application stores its own state files and config files. And when a Utility is run concurrently with an Application it may also store its state file in the bundle. This allows Utilities to, optionally, maintain different state per Application.
Purpose, Interface, Function
An Application must have an overarching purpose. A program more generally, such as one written in BASIC that can be loaded and run from the READY prompt, can be trivially simple. For example, a program might change the border color, switch the character set, and then end, without any input from the user and without any messaging or other output to the user. A program such as this would be inappropriately simple to be instantiated as an Application.
When an Application is launched, the previous Application is no longer in active memory. The loader presents a loading splash screen and shows the icon of the Application. When the new Application is loaded it takes over the whole screen and the menu system. It is therefore expected that the Application will provide some kind of interface which the user can see and interact with in a friendly and intuitive manner.
Therefore, the Application should have some specific job or purpose, that makes it worth the user's time to launch it. The Application should have some main function that gives the user some new ability to perform work a task or complete some meaningful work.
Example ApplicationsC64 OS v1.0 ships with several Applications. Let us consider what those Applications do to get an idea of what it means for an Application to have a purpose and an interface that helps the user complete some task.
App Launcher — has multiple desktops, with configurable hint color and background image. To each desktop the user can add aliases to various Applications, Utilities and non-C64-OS programs. The aliases can be arranged and color coded to give the user the ability to design his own collections that facilitate a workflow. And ultimately gives the user the ability to move quickly between different Apps, Utilities and programs. The menu system provides options for helping to manage the desktops and the aliases, adding new ones, moving and copying them between desktops, removing old ones, and to jump between desktops.
File Manager — lets the user view and navigate the file systems of all of the connected storage devices. With multiple tabs the user can be in multiple places at the same time. The menu system gives the user the ability to jump to common places, or to navigate relatively through directory trees. Other menu options can be used to invoke Utilities to complete special sub-tasks, such as scratching selected files, or moving or copying selected files and directories between the places navigated to within different tabs.
Image Viewer — gives the user metadata display boxes, and the ability to open and view graphic image files. The interface shows the user metadata about the opened image file. The menu options allow the user to open new files, save files to new places, switch between graphics modes, and activate special features of some file types, such as to start animations.
C64 Archiver — provides the user with the ability to create archive files of selected input. The user interface presents options to customize what files will be included in the archive, and what kinds of files should be excluded. It allows the user to set a note, and specify the archive type. The menu system gives the user the option to set custom defaults, to select the starting point, and to set the name and place to create the new archive file. And menu options allow the user to start and cancel the archive process. The rest of the user interface shows the user feedback and progress information about where it is in the job and how much it has completed so far.
Summary
Some are simpler than others; for example Image Viewer is much simpler than File Manager. But they all have a purpose, and a user interface to fulfill that purpose, and they give the user a reason to launch them and spend time there.
When you are writing software for C64 OS, you have to decide if the kind of program you want to write is appropriate to be implemented as an Application. If your program is on the cusp, if it's more than a Utility but it doesn't quite have a full user interface, then it is your job to get creative and imagine how your Application can be fleshed out with features and options to give the user some flexibility in how to access and use the functionality the Application provides.
It is also important to think about how your new Application fits into the larger scheme of C64 OS. Here are some questions you should ask when designing an Application:
- How can it be used alongside other existing Applications?
- How can it integrate the functionality of Utilities to feel like it fits in?
- How can it make use of the Color picker?
- How can it make use of File Info?
- Does it respond gracefully to Theme changes?
- Can it make use of C64 OS shared libraries?
- Can it make use of split screen?
- How does it integrate into the clipboard?
- Can things copied from this new Application be usefully pasted to other Applications?
- Can things copied from other Applications or from Utilities be usefully pasted into this Application?
Next Section: Writing an Application: Tutorial 1: Hello World
Table of Contents
This document is subject to revision updates.
Last modified: Feb 01, 2024