Date: Sat, 8 Sep 2001 04:42:23 +0200

From: Max Horn <[email protected]>
Subject: SDL/OSX: Joystick; Better key handling

I just finished implementing improved keyhandling for OS X (in fact
the code should be easily ported to the "normal" MacOS part of SDL, I
just had no chance yet). Works like this:
First init the mapping table statically like before. Them, it queries
the OS for the "official" key table, then iterates over all 127
scancode and gets the associates ascii code. It ignores everythng
below 32 (has to, as it would lead to many problems if we did not...
e.g. both ESC and NUM LOCk produce an ascii code 27 on my keyboard),
and all stuff above 127 is mapped to SDLK_WORLD_* simply in the order
it is encountered.
In addition, caps lock is now working, too.
The code work flawless for me, but since I only have one keyboard, I
may have not encountered some serious problem... but I am pretty
confident that it is better than the old code in most cases.


The joystick driver works fine for me, too. I think it can be added
to CVS already. It would simply be helpful if more people would test
it. Hm, I wonder if Maelstrom or GLTron has Joystick support? That
would be a wonderful test application :)


I also took the liberty of modifying some text files like BUGS,
README.CVS, README.MacOSX (which now contains the OS X docs I long
promised)

Author: slouken

BUGS

@@ -68,9 +68,9 @@ MacOS:
 	Not all of the keys are properly recognized on the keyboard.
 
 MacOS X:
-	Joystick and CD-ROM functions are not implemented yet.
+	CD-ROM functions are not implemented yet.
 
-	Window management buttons don't draw correctly.
+	Joystick code is not extensively tested yet.
 
 	Window may not close when unsetting video mode and resetting.
 
@@ -98,8 +98,6 @@ MacOS X:
 	cursor in the center of the window/screen.  Also, mouse moved events
 	are not generated, and the keyboard cannot be grabbed.
 
-	Not all of the keys are properly recognized on the keyboard.
-
 	MacOS X seems to have a broken pthread_cancel() implementation.
 
 FreeBSD:

README.CVS

@@ -1,13 +1,13 @@
 
 The latest development version of SDL is available via CVS:
 
-cvs -d :pserver:guest@cvs.lokigames.com:/cvs login
-# use the password "guest"
-cvs -d :pserver:guest@cvs.lokigames.com:/cvs checkout SDL
+cvs -d :pserver:guest@libsdl.org:/home/slouken/libsdl.org/cvs login
+# No password, so just hit enter when prompted for a password
+cvs -d :pserver:guest@libsdl.org:/home/slouken/libsdl.org/cvs checkout SDL
 
 When you check a fresh copy of SDL out of CVS, you need to generate
 the files used by make by running the "autogen.sh" script, which will
 run aclocal, automake, autoconf and then run configure.
 
-There is a web interface to cvs at http://cvs.lokigames.com/
+There is a web interface to cvs at http://www.libsdl.org/cgi/cvsweb.cgi
 

README.MacOS

@@ -52,9 +52,12 @@ IV.  Enjoy! :)
   If you have a project you'd like me to know about, or want to ask questions,
   go ahead and join the SDL developer's mailing list by sending e-mail to:
 
-	[email protected]
+	[email protected]
 
-  and put the line "subscribe sdl" in the body of the message.
+  and put "subscribe" into the subject of the message. Or alternatively you
+  can use the web interface:
+
+	http://www.libsdl.org/mailman/listinfo/sdl
 
 ==============================================================================
 

README.MacOSX

@@ -18,11 +18,7 @@ process:
 
 (You may need to create the subdirs of /usr/local manually.)
 
-For some reason, libtool doesn't run ranlib properly, so do this
-manually:
-
-	ranlib /usr/local/lib/libSDL.a
-
+/*
 To use the library once it's built, you need to use the "Carbon
 framework", which is the port of the old Mac Toolbox to OS X.
 To do this, use the -F and -framework arguments for compiling
@@ -33,6 +29,79 @@ and linking, respectively:
 
 sdl-config knows about the linking path and -framework, so it's
 recommended to use it to fill in your Makefile variables.
+*/
+
+To use the library once it's built, you essential have two possibilities:
+use the traditional autoconf/automake/make method, or use Apple's Project Builder.
+
+==============================================================================
+Using the Simple DirectMedia Layer with a traditional Makefile
+==============================================================================
+
+In the following, it will be mostly assumed that you are using autoconf and
+automake to setup your SDL project, and furthermore that you use the AM_PATH_SDL
+macro provided by SDL in sdl.m4. If you are not using these tools, you can
+still use SDL but it will be somewhat hard to get running.
+
+Only step 1) is really required to get started, but for full OS X support you
+will want to do the other steps, too.
+
+1) Update your acinclude.m4 file in case you have copied an older version of
+   sdl.m4 into it. This is essential as AM_PATH_SDL now performs some additional
+   tasks when used on MacOS X
+
+   Rationale: AM_PATH_SDL copies /usr/local/share/sdl/Info.plist and the folder
+   /usr/local/share/sdl/SDLMain.nib/ into the directory where configure is invoked.
+   This is essential for the configure script to be able to run the test code
+   that detects SDL.
+
+2) Copy SDL's Info.plist.in file (from src/main/macosx) into your project's main
+   folder (the same spot that your configure.in sits), and edit it to suite your
+   needs. Then add it to your AC_OUTPUT list in configure.in
+
+   Rationale: The Info.plist file can be used to specify an icon file for
+   your app, and also to provide a human readable version/copyright string
+   and other meta-information to the user via the Finder's Get Info dialog.
+
+3) Add something like the following rule to your Makefile.am:
+
+APP_NAME.app: EXE_NAME
+	mkdir -p $@/Contents/MacOS
+	mkdir -p $@/Contents/Resources
+	mkdir -p $@/Contents/Resources/SDLMain.nib
+	echo "APPL????" > $@/Contents/PkgInfo
+	$(INSTALL_DATA) Info.plist $@/Contents/
+	$(INSTALL_DATA) SDLMain.nib/*.nib $@/Contents/Resources/
+	$(INSTALL_PROGRAM) $< $@/Contents/MacOS/
+
+   You should replace EXE_NAME with the name of the executable. APP_NAME is what
+   will be visible to the user in the Finder. Usually it will be the same
+   as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
+   usually is "TestGame"
+
+   If your project builds more than one application, you will have to do a bit more.
+   For each of your target applications, you need a seperate rule. Furthermore, each
+   needs its own Info.plist file, since that has to contain the exact name of the 
+   executable (i.e. EXE_NAME above). One way to do that is to use sed in your make rules
+   and modify a single master Info.plist.
+
+   Rationale: on Mac OS X, executables have to be put into so-called "bundles".
+   The make rule given above will construct such a bundle around the executable
+   for you. You need to make a copy of it for each target application.
+
+4) If you want the create bundles to be installed, you may want to add this
+   rule to your Makefile.am:
+
+install-exec-local: Exult.app
+	mkdir -p /Applications/
+	cp -r $< /Applications/
+
+   This rule takes the Bundle created by the rule from step 3 and installs them
+   into /Applications/. An alternate installation place would be $HOME/Applications/
+
+   Again, if you want to install multiple applications, you will have to augment
+   the make rule accordingly.
+
 
 ==============================================================================
 Using the Simple DirectMedia Layer with Project Builder
@@ -122,3 +191,4 @@ following locations:
         but I expect that things will still work on older versions.
 
 Known bugs are listed in the file "BUGS"
+ LocalWords:  Stuffit

configure.in

@@ -2056,8 +2056,8 @@ case "$target" in
         fi
         # Set up files for the joystick library
         if test x$enable_joystick = xyes; then
-            JOYSTICK_SUBDIRS="$JOYSTICK_SUBDIRS dummy"
-            JOYSTICK_DRIVERS="$JOYSTICK_DRIVERS dummy/libjoystick_dummy.la"
+            JOYSTICK_SUBDIRS="$JOYSTICK_SUBDIRS darwin"
+            JOYSTICK_DRIVERS="$JOYSTICK_DRIVERS darwin/libjoystick_darwin.la"
         fi
         # Set up files for the cdrom library
         if test x$enable_cdrom = xyes; then
@@ -2192,6 +2192,7 @@ include/Makefile
 src/Makefile
 src/main/Makefile
 src/main/macosx/Makefile
+src/main/macosx/Info.plist
 src/audio/Makefile
 src/audio/alsa/Makefile
 src/audio/arts/Makefile
@@ -2236,6 +2237,7 @@ src/events/Makefile
 src/joystick/Makefile
 src/joystick/amigaos/Makefile
 src/joystick/beos/Makefile
+src/joystick/darwin/Makefile
 src/joystick/dummy/Makefile
 src/joystick/linux/Makefile
 src/joystick/macos/Makefile

sdl.m4

@@ -32,6 +32,7 @@ AC_ARG_ENABLE(sdltest, [  --disable-sdltest       Do not try to compile and run
      fi
   fi
 
+  AC_REQUIRE([AC_CANONICAL_TARGET])
   AC_PATH_PROG(SDL_CONFIG, sdl-config, no)
   min_sdl_version=ifelse([$1], ,0.11.0,$1)
   AC_MSG_CHECKING(for SDL - version >= $min_sdl_version)

src/joystick/Makefile.am

@@ -5,7 +5,7 @@ noinst_LTLIBRARIES = libjoystick.la
 
 # Define which subdirectories need to be built
 SUBDIRS = @JOYSTICK_SUBDIRS@
-DIST_SUBDIRS = dummy amigaos beos linux macos win32
+DIST_SUBDIRS = dummy amigaos beos darwin linux macos win32
 
 DRIVERS = @JOYSTICK_DRIVERS@
 

src/joystick/darwin/.cvsignore

@@ -0,0 +1,6 @@
+Makefile.in
+Makefile
+.libs
+*.o
+*.lo
+*.la

src/joystick/darwin/Makefile.am

@@ -0,0 +1,8 @@
+
+## Makefile.am for the darwin/MacOS X joystick driver for SDL
+
+noinst_LTLIBRARIES = libjoystick_darwin.la
+libjoystick_darwin_la_SOURCES = $(SRCS)
+
+# The SDL joystick driver sources
+SRCS =  SDL_sysjoystick.c