Updated RDoc a bit for FXAccelTable#addAccel

lib/fox16/accel_table.rb

@@ -4,20 +4,44 @@ module Fox
     
     #
     # Add an accelerator to the table. The _hotKey_ is a code returned
-    # by the Fox.fxparseAccel method. For example, to associate the
-    # Ctrl+S keypress with sending a "save" command to a document, you
-    # might use code like this:
+    # by the Fox.fxparseAccel method.
     #
-    #   hotKey = fxparseAccel("Ctrl+S")
-    #   accelTable.addAccel(hotKey, doc, FXSEL(SEL_COMMAND, MyDocument::ID_SAVE))
+    # There are several forms for _addAccel_; the original form (from FOX)
+    # takes either three or four arguments. For example, to associate the
+    # Ctrl+H keypress with sending the "hide" command to a window, you might
+    # use code like this:
     #
-    # A more straightforward way is to pass one or more callable objects in:
+    #   hotKey = fxparseAccel("Ctrl+H")
+    #   accelTable.addAccel(hotKey, window, FXSEL(SEL_COMMAND, FXWindow::ID_HIDE))
     #
-    #   accelTable.addAccel(hotKey, lambda { doc.save })
+    # If you instead want to trigger the command on the key release (instead of
+    # the key press), pass a zero for the third argument and pass the command
+    # as the fourth argument:
     #
-    # or to trigger the event on the key "up" event,
+    #   accelTable.addAccel(hotKey, window, 0, FXSEL(SEL_COMMAND, FXWindow::ID_HIDE))
     #
-    #   accelTable.addAccel(hotKey, nil, lambda { doc.save })
+    # You can even pass in two different messages, corresponding to the key press
+    # and key release events for the hot key, although this is less common.
+    #
+    #   accelTable.addAccel(hotKey, window,
+    #     FXSEL(SEL_COMMAND, FXWindow::ID_HIDE),
+    #     FXSEL(SEL_COMMAND, FXWindow::ID_SHOW))
+    #
+    # The problem with this form is that you need to be familiar with the message
+    # types and identifiers that different widgets respond to, and this information
+    # isn't very well documented. A more straightforward way to use _addAccel_
+    # from Ruby code is to instead pass one or more callable objects in as the
+    # second and third arguments. For example:
+    #
+    #   accelTable.addAccel(hotKey, lambda { window.hide })
+    #
+    # or to trigger the event on the key release event:
+    #
+    #   accelTable.addAccel(hotKey, nil, lambda { window.hide })
+    #
+    # Or to handle both the key press and key release events:
+    #
+    #   accelTable.addAccel(hotKey, lambda { window.hide }, lambda { window.show })
     #
     def addAccel(hotKey, *args)
       tgt, seldn, selup = nil, 0, 0