content/blog/2017/01/chip8-menus.markdown @ 40accabe3a95 default tip
Update
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Mon, 18 Mar 2024 15:47:07 -0400 |
| parents | f5556130bda1 |
| children | (none) |
( :title "CHIP-8 in Common Lisp: Menus" :snip "Let's add some polish." :date "2017-01-10T16:20:00Z" :draft nil ) Our [CHIP-8][] emulator in Common Lisp is almost complete. It can play games, and we've got a rudimentary debugging system in place so we can figure out where things go wrong. Up to now we've been communicating with the running emulator mostly through NREPL or SLIME. This is fine for development, but in this post we'll add some much-needed polish in the form of menus. This is the kind of boring work that often gets left until the end during game development, so let's just get it out of the way. The full series of posts so far: 1. [CHIP-8 in Common Lisp: The CPU](http://stevelosh.com/blog/2016/12/chip8-cpu/) 2. [CHIP-8 in Common Lisp: Graphics](http://stevelosh.com/blog/2016/12/chip8-graphics/) 3. [CHIP-8 in Common Lisp: Input](http://stevelosh.com/blog/2016/12/chip8-input/) 4. [CHIP-8 in Common Lisp: Sound](http://stevelosh.com/blog/2016/12/chip8-sound/) 5. [CHIP-8 in Common Lisp: Disassembly](http://stevelosh.com/blog/2017/01/chip8-disassembly/) 6. [CHIP-8 in Common Lisp: Debugging Infrastructure](http://stevelosh.com/blog/2017/01/chip8-debugging-infrastructure/) 7. [CHIP-8 in Common Lisp: Menus](http://stevelosh.com/blog/2017/01/chip8-menus/) The full emulator source is on [BitBucket][] and [GitHub][]. [CHIP-8]: https://en.wikipedia.org/wiki/CHIP-8 [BitBucket]: https://bitbucket.org/sjl/cl-chip8 [GitHub]: https://github.com/sjl/cl-chip8 <div id="toc"></div> ## Architecture Qtools has some [rudimentary support][qtools-menus] for menus. Unfortunately it won't quite work with our emulator as-is, so we'll need to shuffle things around a bit. When we added the screen to the emulator back in the [graphics][] post we just created a subclass of `QGLWidget` and passed it along to `with-main-window`. This works for displaying the screen, but if you try to `define-menu` on this widget Qtools will signal an error. [qtools-menus]: https://shinmera.github.io/qtools/#QTOOLS:DEFINE-MENU [graphics]: http://stevelosh.com/blog/2016/12/chip8-graphics/ What we need to do is create a `QMainWindow` widget instead, and put our `QGLWidget` inside of that. Then we can add some menus to the main window and everything should work great. It will end up being structured like this: <pre class="lineart"> QMainWindow ╔══════════════════════════════════╗ ║ Menu1 │ Menu2 │ ... ║ ║───────┴───────┴──────────────────║ ║ ┌──────────────────────────────┐ ║ ║ │..............................│ ║ ║ │..............................│ ║ ║ │..........QGLWidget...........│ ║ ║ │.........(the screen).........│ ║ ║ │..............................│ ║ ║ │..............................│ ║ ║ │..............................│ ║ ║ └──────────────────────────────┘ ║ ╚══════════════════════════════════╝ </pre> ## Adding a Main Window We'll start by creating the `QMainWindow` widget. It will just have a single slot to keep track of the `chip` struct it's displaying: ```lisp (define-widget main-window (QMainWindow) ((chip :accessor main-chip :initarg :chip))) ``` Next we'll define our screen widget to be a *subwidget* of the main window: ```lisp (define-subwidget (main-window screen) (make-instance 'screen) (setf (screen-chip screen) chip)) ``` This ensures the screen widget will get cleaned up properly when the main window is closed. Now we need to move some of the initialization code that used to be in the screen widget up into the main window, and also add a bit more to connect everything properly: ```lisp (define-initializer (main-window main-setup) (setf (q+:window-title main-window) "cl-chip8" (q+:central-widget main-window) screen (q+:focus-proxy main-window) screen)) ``` The `window-title` needs to go on the top-level widget, so we can pull that out of the screen's initializer. We also set the screen to be the "central widget" of the main window. You can read the [Qt docs][central widget] for the full story, but essentially a `QMainWindow` is just a container for other widgets and we need to designate one as the primary widget. We'll also want to set the [focus proxy][] of the main window to be the screen, because we want the screen to handle keyboard input just like before. Setting the focus proxy tells Qt that whenever the main window gets focused it should actually focus the screen instead. If we didn't do this, then if the main window itself got focused (which can happen when tabbing through applications, clicking the title bar, etc) it wouldn't propagate the keystrokes down to the screen. This is all kind of fiddly stuff, but it's the polish that separates a toy project from something that actually feels [finished][]. [focus proxy]: https://doc.qt.io/qt-4.8/qwidget.html#setFocusProxy [central widget]: https://doc.qt.io/qt-4.8/qmainwindow.html [finished]: http://makegames.tumblr.com/post/1136623767/finishing-a-game We'll also want to change our `die` function to close this main window, not just the screen. I'm going to cheat just a little bit and use a global variable to hold the currently-running main window for easy access: ```lisp (defparameter *main-window* nil) ; will get set later (defun die () (setf (chip8::chip-running (main-chip *main-window*)) nil) (q+:close *main-window*)) ``` Finally, `run-gui` will need to start up a `main-window` instead of a screen: ```lisp (defun make-main-window (chip) (make-instance 'main-window :chip chip)) (defun run-gui (chip thunk) (with-main-window (window (setf *main-window* (make-main-window chip))) ; NEW (funcall thunk))) ``` I usually try not to use the return value of a `setf` form because I think it's kind of ugly, but it saved an entire `let` here so decided to I break my own style rule. ## Updating the Screen The only thing we need to change for the `screen` is its initializer: ```lisp (define-initializer (screen screen-setup) (setf (q+:focus-policy screen) (q+:qt.strong-focus) (q+:fixed-size screen) (values *width* *height*))) ``` We've removed the useless `window-title` that used to be here. Instead we set the focus policy to the screen to accept all kinds of focus. If you *don't* set this the widget will never be able to get focus (and thus receive keyboard events). We also leave in the size setting. The `QMainWindow` seems to pick up this size and scale itself appropriately, which is nice. That's it for the architectural changes. All the screen's drawing and input-handling code can remain unchanged. ## Adding Menus We'll add a couple of menus to make it a bit easier to use the emulator without falling back to the Lisp REPL. There's a lot of things we could add, so I'll just cover a couple basic options. ### The File Menu Let's start with a simple `File` menu that will just have two items: * Load a ROM * Quit the emulator The menu definition is pretty straightforward: ```lisp (define-menu (main-window File) (:item ("Load ROM..." (ctrl o)) (load-rom main-window)) (:item ("Quit" (ctrl q)) (die))) ``` Note that we use the Windows-centric shortcut key names. Qt will handle translating those to Mac-friendly versions when running on OS X. We'll hide the details of loading the ROM in a `load-rom` helper function: ```lisp (defun load-rom (main-window) (let ((rom (get-rom-path main-window))) (when rom (chip8::load-rom (main-chip main-window) rom)))) ``` `load-rom` just gets the path to load and loads it into the `chip` struct, assuming it's not `nil`. Once again we use a helper function to hide the details of getting the path to the ROM, because I'm a firm believer in [one function to a function][1f]: [1f]: https://groups.google.com/forum/message/raw?msg=comp.lang.lisp/9SKZ5YJUmBg/Fj05OZQomzIJ ```lisp (defparameter *default-directory* (uiop:native-namestring (asdf:system-source-directory :cl-chip8))) (defun get-rom-path (window) (let ((path (q+:qfiledialog-get-open-file-name window ; parent widget "Load ROM" ; dialog title *default-directory* ; starting directory "ROM Files (*.rom);;All Files (*)"))) ; filters (if (string= path "") nil path))) ``` Qt has a nice static method `QFileDialog.getOpenFileName` that we can use to do the heavy lifting. It takes a parent widget (our main window), a title, a directory to start in, and a file filter string. I've used some handy ASDF and UIOP functions to tell the file dialog to start in the directory where the emulator's code is located, because that's where I store my own ROMs. Another option would be to have it start in the user's home directory, or to make the location configurable. The filter string is actually parsed by Qt, and by default will prevent the user from selecting any file that doesn't end in `.rom`. You might want to add a few more options extensions here if you think people will have named their ROMs differently. We also add a second filter that will let the user select *any* file, in case they have a ROM with a filename we haven't anticipated. The result looks like this: [](/static/images/blog/2017/01/chip8-file-select.png) Note that if the user cancels out of the file selection dialog Qt will return an empty string. We'll check for that and return a more Lispy `nil` from the function. That's it for the `File` menu. It's basic, but it's a lot nicer to load ROMs through a normal dialog than to have to poke at the `chip` in the REPL. ### The Display Menu Back in the [graphics][] post we saw how some ROMs expect the CHIP-8 to wrap sprites around the screen when their coordinates get too large, and other ROMs require that they *not* wrap. There's no good way to automatically detect this (aside from hashing particular ROMs and hard-coding the setting for those) so we'll expose this as an option to the user in a `Display` menu. The menu itself is simple — we'll make a submenu that will contain the options and a helper function to actually do the work: ```lisp (define-menu (main-window Display) (:menu "Screen Wrapping" (:item "On" (set-screen-wrapping main-window t)) (:item "Off" (set-screen-wrapping main-window nil)))) (defun set-screen-wrapping (main-window enabled) (setf (chip8::chip-screen-wrapping-enabled (main-chip main-window)) enabled)) ``` Now we've got a simple little menu for turning screen wrapping off and on: [](/static/images/blog/2017/01/chip8-display.png) You might also want to reset the emulator automatically whenever this option is changed, because toggle screen wrapping as the emulator is running can produce... *interesting* results. But I like breaking games in fun ways, so I left it as-is. In a perfect world these options wouldn't be vanilla `:item`s but would instead be part of a [`QActionGroup`][action-group]. This would tell Qt to treat these items as a group, put a checkmark next to the currently-selected one, and so on. Unfortunately Qtools doesn't have a menu content type for action groups and the thought of implementing [something like this][menu-content] makes me nauseas, so I'm satisfied with the `:item` kludge. [action-group]: https://doc.qt.io/qt-4.8/qactiongroup.html [menu-content]: https://github.com/Shinmera/qtools/blob/23e3e44/widget-menu.lisp#L67-L86 ### The Sound Menu Our final menu will allow the user to select what kind of sound the buzzer should play, because it would be a shame to let all our work in the [sound][] post go to waste. We'll implement the `Sound` menu just like the `Display` menu: [sound]: http://stevelosh.com/blog/2016/12/chip8-sound/ ```lisp (define-menu (main-window Sound) (:menu "Sound Type" (:item "Sine" (set-sound-type main-window :sine)) (:item "Square" (set-sound-type main-window :square)) (:item "Sawtooth" (set-sound-type main-window :sawtooth)) (:item "Triangle" (set-sound-type main-window :triangle)))) (defun set-sound-type (main-window type) (setf (chip8::chip-sound-type (main-chip main-window)) type)) ``` ## Results And with that we've got a basic menu system for the emulator: [](/static/images/blog/2017/01/chip8-menu.png) ## Future We're nearing the end of the series. The next post will be about adding a graphical debugging interface, and will probably be the last in the series. (Unless I get ambitious and try making a curses-based ASCII UI...)