<- Home

Atari index / news

Atari development with C

Atari programs with C-sources

Hatari UI

Hatari for:
- N900
- N800/N810
- N770

Debian packaged Atari games and demos

Control and debugger UI for Hatari

• Introduction
  • Why another UI?
  • Current features
  • Future features
  • Known issues
• Getting Hatari UI
  • Portability
• Screenshots
  • Latest version screenshot
  • Older versions screenshots
• Command line usage
  • Keycodes

Introduction

Hatari UI is an out-of-process user interface for the Hatari emulator and its built-in debugger which can (optionally) embed the Hatari emulator window. Having the UI in another process allows doing it with a higher level language and avoiding adding GUI toolkit dependencies to Hatari itself.

The UI is done with PyGtk i.e. in Python language, using the Gtk widget set. It's an additional UI, the built-in Hatari SDL UI isn't being replaced or going anywhere!

Why another UI?

While the built-in SDL UI for Hatari has its good points, it has also many minor shortcomings:

• There's no UI for the debugger or for viewing trace/debug logs.
• The configuration UI itself is not configurable and although its quite nice for an UI done with C and libSDL, it's still very hard to modify (e.g. its layout).
• It doesn't currently support UTF-8 or internationalization and isn't scalable enough to support localization well (translations need upto 1/3 more space).
• The file selector doesn't support unicode (all file systems use nowadays Unicode file names) nor bookmarks or other goodies in modern file selectors.
• Invoking the UI stops the emulation.
• It doesn't allow configuring all the things that one can configure e.g. from command line (Spec512, fast forward,Falcon DSP settings, trace settings and bios-tracing, log files and levels).

As you can see from the screenshots, the features offered by the new UI are nice also on desktops, but the configurability is especially important for devices that have constrained input methods; limited set of keys and e.g. high DPI touchscreen. Something like this UI is really a must on devices with no right or middlebutton, where use of stylus or finger makes double clicks hard because the pixels are so small that hitting the same place twice is not easy and which lacks standard Atari keys.

One of the targets for the UI configurability and features is Nokia N8x0 (Linux) devices with 226 DPI 800x480 touchscreen and limited number of keys. This reflects slightly in the UI design too. For example text pasting is done in separate dialog instead of in an inline control and one can easily add buttons for synthetizing specific key presses.

Current features

• Besides the UI menu, user can specify whether there are toolbars, where they are (on left, right, top or bottom, or in a separate panel window) and what controls the toolbars have (from a predefined set).
• Optional support for embedding the Hatari window (UI keyboard shortcuts would prevent those keys from being used with Hatari so keyboard shortcuts are disabled when Hatari window is embedded).
• User can specify buttons which synthetize specified text strings or Atari keycodes to the emulator. There's also a dialog for pasting text (e.g. from other programs) to Hatari.
• An UI for the Hatari debugger and dialog for changing the emulation tracing points at run time.
• An ability to pause Hatari completely.
  (SDL UI cannot do this because SDL does constant polling even when Hatari is completely idle; on OSX this prevents screensaver from starting and on laptops it drains the battery.)
• Support all main options that can affect Hatari speed (frameskip, fastforward, spec512 and sound) without a need to reset the emulation and dialogs for configuring the other main Hatari options (which require reset).
• Gtk file selector used for floppies, harddisks, ROMs etc.
• Saving and loading Hatari configurations (user can have multiple setups between which he can switch such as STE+color for demos vs. TT+mono for applications).

See screenshots for more details.

Future features

There are several other features that would be nice in the new UI:

• Support for less often used Hatari options (printer, DSP settings etc).
• Multiple views to registers, emulated memory areas or disassembly which are refreshed by the debugger UI each time the emulator is stopped.
• Debugger breakpoint support.
• Trace/debug log view window with log level controls.
• Saving/loading the configuration for Hatari UI itself.
• Saving Hatari configuration changes to separate file from configuration file Hatari normally reads.
• UI internationalization and localization (after somebody asks for it).

Known issues

There are some minor issues which cannot be handled in an external UI without additional support from Hatari:

• Hatari UI doesn't notice nor adapt if user changes Hatari configuration options from within Hatari itself (as Hatari doesn't currently tell about them). This isn't very serious issue as with Hatari UI, the configuration changes are supposed to be done through it, not by using the interal Hatari UI.
• To take Machine setup "Use harddisk" option disabling into use, it's not enough to reboot the emulation. You need to re-run Hatari as Hatari doesn't support doing that externally at run-time.

Getting Hatari UI

Hatari is available from major Linux distributions and Hatari UI is included with it. The latest version can be gotten from the Hatari Mercurial repository under the python-ui directory: http://hg.tuxfamily.org/mercurialroot/hatari/hatari/file/tip/python-ui.

In Debian and Ubuntu distributions Mercurial is in "mercurial" package. After installing it, you can read quick instructions: http://mercurial.selenic.com/wiki/QuickStart and get Hatari sources with:
hg clone http://hg.tuxfamily.org/mercurialroot/hatari/hatari

Portability

Besides Linux, the UI could eventually be used even on Windows by first installing the PyGtk dependencies listed on (otherwise unrelated) Gramps application Windows dependencies page. Additionally the Hatari control socket code needs to be ported to Windows (i.e. use WinSock or have proper Cygwin build of Hatari with unix domain socket support).

OSX shouldn't be a problem, under its UI glitz it's mostly BSD unix.

Screenshots

Latest version screenshot

Latest Hatari UI version uses standard Gtk menu and toolbars instead of the button boxes used in older versions. You can still configure the buttons included to the top / bottom / left / right of the Hatari screen though.

hatari-ui.py --embed --right "about,|,run,pause,forward,|,reset,|,quit"

Older versions screenshots

hatari-ui.py --embed
--top "about,run,pause,reset,screenshot,setup,quit"
--panel "Input,..."
--panel "Speed settings,..."
--bottom "debug,trace,peripherals,Speed settings,Input"

hatari-ui.py
--top "about,run,pause,quit"
--panel "Function keys,..."
--panel "Other keys,..."
--right "setup,debug,trace,Function keys,Other keys"
--bottom "sound,spec512,|,fastforward,|,frameskip"

--panel "Speed settings,frameskip,>,fastforward,|,spec512,|,sound,>,close"

Command line usage

Hatari UI v0.9
==============

Usage: hatariui.py [options] [floppy image]

Options:
	-h, --help		this help
	-n, --nomenu		omit menus
	-e, --embed		embed Hatari window in middle of controls
	-f, --fullscreen	start in fullscreen
	-l, --left <controls>	toolbar at left
	-r, --right <controls>	toolbar at right
	-t, --top <controls>	toolbar at top
	-b, --bottom <controls>	toolbar at bottom
	-p, --panel <name>,<controls>
				separate window with given name and controls

Available (toolbar) controls:
	|		Separator between controls
	>		Next toolbar in panel windows
	recanim		Record animation
	floppy		Floppy images
	recsound	Record YM/Wav
	pause		Pause Hatari to save battery
	run		(Re-)run Hatari
	display		Display settings
	sound		Sound settings
	path		Device & save file paths
	sconfig		Save configuration
	load		Load emulation snapshot
	trace		Hatari tracing setup
	save		Save emulation snapshot
	reset		Warm or cold reset Hatari
	machine		Hatari st/e/tt/falcon configuration
	about		Hatari UI information
	shot		Grab a screenshot
	full		Toggle whether Hatari is fullscreen
	device		Toggle Midi, Printer, RS232 peripherals
	input		Simulate text input and mouse clicks
	debug		Activate Hatari debugger
	forward		Whether to fast forward Hatari (needs fast machine)
	quit		Quit Hatari UI
	lconfig		Load configuration
	joystick	Joystick settings
	<panel name>	Button for the specified panel window
	<name>=<string/code>
			Synthetize string or single key <code>

You can have as many panels as you wish.  For each panel you need to add
a control with the name of the panel (see "MyPanel" below).

For example:
	hatariui.py --embed \
	-t "about,run,pause,quit" \
	-p "MyPanel,Macro=Test,Undo=97,Help=98,>,F1=59,F2=60,F3=61,F4=62,>,close" \
	-r "paste,debug,trace,machine,MyPanel" \
	-b "sound,|,fastforward,|,fullscreen"

if no options are given, the UI uses basic controls.

Keycodes

To configure the keys, you need Atari keycode map, here's one for ST: