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 4: Using the KERNAL → Menu (module)
The Menu System
The menu KERNAL module is responsible for drawing the menu bar that runs along the top of the screen, including its hierarchical pull down menus. The menu system also draws the status bar that runs along the bottom of the screen. The menu module handles everything that makes the menus work; It does drawing and event handling.
The menu bar and status bar are drawn on a fourth screen layer, index 3. This layer behaves like any other screen layer, except that it is not part of the layerpush and layerpop stack outlined in the screen KERNAL module above.
Every Application must integrate with the menu bar and status bar in some minimal way. Each Application must provide a valid menu definitions file (menu.m) found in the root of the Application's bundle. The Application must handle the two message types: Menu Enquiries (mc_menq) and Menu Actions (mc_mnu). Integration with the menu system is covered in more detail in Chapter 7: Writing an Application.
mnudraw
| Purpose | Draws the current state of the menus and status bar. |
|---|---|
| Module offset | 0 |
| Communication registers | None |
| Stack requirements | 6 bytes + |
| Zero page usage | $26, $27, $4e, $4f, $50, $51, $52, $53 |
| Registers affected | A, X, Y |
| Input parameters | None |
| Output parameters | None |
Description: This routine should not be called by end-user software. This routine is pointed to by the draw vector (sldraw) for the menu bar and status bar screen layer. This screen layer is managed automatically. The mnudraw routine, thus, is called just like any other screen layer draw routine, when the menu screen layer is dirty or needs to be redrawn for compositing reasons.
mnumouse
| Purpose | Allows the menu system to process mouse events. |
|---|---|
| Module offset | 3 |
| Communication registers | None |
| Stack requirements | 6 bytes + |
| Zero page usage | $4e, $4f |
| Registers affected | A, X, Y |
| Input parameters | None |
| Output parameters | None |
Description: This routine should not be called by end-user software. This routine is pointed to by the mouse vector (slmous) for the menu bar and status bar screen layer. This screen layer is managed automatically. The mnumouse routine, thus, is called just like any other screen layer mouse routine, when a low-level mouse event is generated. If the mouse event is not handled by the menu system it is allowed to propagate to lower screen layers.
The amount of stack that this routine uses is dependent on the size of the menu hierarchy that needs to be recursively traversed.
mnukcmd
| Purpose | Allows the menu system to process key command events. |
|---|---|
| Module offset | 6 |
| Communication registers | None |
| Stack requirements | 6 bytes + |
| Zero page usage | $4e, $4f |
| Registers affected | A, X, Y |
| Input parameters | None |
| Output parameters | None |
Description: This routine should not be called by end-user software. This routine is pointed to by the key command vector (slkcmd) for the menu bar and status bar screen layer. This screen layer is managed automatically. The mnukcmd routine, thus, is called just like any other screen layer key command routine, when a low-level key command event is generated. If the key command event is not handled by the menu system it is allowed to propagate to lower screen layers. The menu system does not process printable key events, its screen layer propagates them automatically, without analysis.
The amount of stack that this routine uses is dependent on the size of the menu hierarchy that needs to be recursively traversed.
deactiv
| Purpose | Closes all open menus and markes the menu system as inactive. |
|---|---|
| Module offset | 9 |
| Communication registers | None |
| Stack requirements | 6 bytes + |
| Zero page usage | $4e, $4f, $50, $51 |
| Registers affected | A, X, Y |
| Input parameters | None |
| Output parameters | None |
Description: This routine does not usually need to be called by end-user software. This routine deactivates the menus, if they are currently active due to mouse event interaction, and then recursively closes all open menus. This routine is used for some unusual circumstances in which a process that draws suddenly takes control away from an Application. Examples of this include the Loader (which runs to facilitate quitting one Application and loading in the next), and the crash.lib (which displays a crash screen when an exception is unhandled.)
KERNAL Modules in Alphabetical Order
KERNAL Modules in Module Lookup Table Order
Return to Using the KERNAL → KERNAL Modules
Table of Contents
This document is subject to revision updates.
Last modified: Apr 20, 2023