all: revise documentations

Author: changkun

README.md

@@ -13,56 +13,16 @@ import "golang.design/x/hotkey"
 
 ## API Usage
 
-Package `hotkey` provides the basic facility to register a system-level
-hotkey so that the application can be notified if a user triggers the
-desired hotkey. By definition, a hotkey is a combination of modifiers
-and a single key, and thus register a hotkey that contains multiple
-keys is not supported at the moment. Furthermore, because of OS
-restriction, hotkey events must be handled on the main thread.
+Package hotkey provides the primary facility to register a system-level global hotkey shortcut to notify an application if a user triggers the desired hotkey. A hotkey must be a combination of modifiers and a single key.
 
-Therefore, in order to use this package properly, here is a complete
-example that corporates the mainthread:
-package:
-
-```go
-package main
-
-import (
-	"context"
-
-	"golang.design/x/hotkey"
-	"golang.design/x/hotkey/mainthread"
-)
-
-// initialize mainthread facility so that hotkey can be
-// properly registered to the system and handled by the
-// application.
-func main() { mainthread.Run(fn) }
-func fn() { // Use fn as the actual main function.
-	var (
-		mods = []hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}
-		k    = hotkey.KeyS
-	)
-
-	// Register a desired hotkey.
-	hk := hotkey.New(mods, k)
-	if err := hk.Register() err != nil {
-		panic("hotkey registration failed")
-	}
-
-	// Start listen hotkey event whenever you feel it is ready.
-	for range hk.Listen() {
-		println("hotkey ctrl+shift+s is triggered")
-	}
-}
-```
+Note a platform-specific detail on `macOS` due to the OS restriction (other platforms do not have this restriction): hotkey events must be handled on the "main thread". Therefore, to use this package properly, one must call the `(*Hotkey).Register` method on the main thread, and an OS app main event loop must be established. One can use  the provided `golang.design/x/hotkey/mainthread` for self-contained applications. For applications based on other GUI frameworks, one has to use their provided ability to run the `(*Hotkey).Register` on the main thread. See the [examples](./examples) folder for more examples.
 
 ## Who is using this package?
 
 The main purpose of building this package is to support the
 [midgard](https://changkun.de/s/midgard) project.
 
-To know more projects, check our [wiki](https://github.com/golang-design/clipboard/wiki) page.
+To know more projects, check our [wiki](https://github.com/golang-design/hotkey/wiki) page.
 
 ## License
 

example/main.go

@@ -0,0 +1 @@
+TODO

examples/README.md

@@ -1,3 +1,5 @@
 module golang.design/x/hotkey
 
 go 1.17
+
+require golang.design/x/mainthread v0.3.0

go.mod

@@ -0,0 +1,4 @@
+golang.design/x/mainthread v0.3.0 h1:UwFus0lcPodNpMOGoQMe87jSFwbSsEY//CA7yVmu4j8=
+golang.design/x/mainthread v0.3.0/go.mod h1:vYX7cF2b3pTJMGM/hc13NmN6kblKnf4/IyvHeu259L0=
+golang.org/x/sys v0.0.0-20201022201747-fb209a7c41cd h1:WgqgiQvkiZWz7XLhphjt2GI2GcGCTIZs9jqXMWmH+oc=
+golang.org/x/sys v0.0.0-20201022201747-fb209a7c41cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=

go.sum

@@ -5,45 +5,19 @@
 // Written by Changkun Ou <changkun.de>
 
 // Package hotkey provides the basic facility to register a system-level
-// hotkey so that the application can be notified if a user triggers the
-// desired hotkey. By definition, a hotkey is a combination of modifiers
-// and a single key, and thus register a hotkey that contains multiple
-// keys is not supported at the moment. Furthermore, because of OS
-// restriction, hotkey events must be handled on the main thread.
+// global hotkey shortcut so that an application can be notified if a user
+// triggers the desired hotkey. A hotkey must be a combination of modifiers
+// and a single key.
 //
-// Therefore, in order to use this package properly, here is a complete
-// example that corporates the golang.design/x/hotkey/mainthread package:
-//
-// 	package main
-//
-// 	import (
-// 		"context"
-//
-// 		"golang.design/x/hotkey"
-// 		"golang.design/x/hotkey/mainthread"
-// 	)
-//
-// 	// initialize mainthread facility so that hotkey can be
-// 	// properly registered to the system and handled by the
-// 	// application.
-// 	func main() { mainthread.Run(fn) }
-// 	func fn() { // Use fn as the actual main function.
-// 		var (
-// 			mods = []hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}
-// 			k    = hotkey.KeyS
-// 		)
-//
-// 		// Register a desired hotkey.
-// 		hk := hotkey.New(mods, k)
-// 		if err := hk.Register(); err != nil {
-// 			panic("hotkey registration failed")
-// 		}
-//
-// 		// Start listen hotkey event whenever you feel it is ready.
-// 		for range hk.Listen() {
-// 			println("hotkey ctrl+shift+s is triggered")
-// 		}
-// 	}
+// Note a platform specific detail on "macOS" due to the OS restriction (other
+// platforms does not have this restriction), hotkey events must be handled
+// on the "main thread". Therefore, in order to use this package properly,
+// one must call the "(*Hotkey).Register" method on the main thread, and an
+// OS app main event loop must be established. For self-contained applications,
+// collaborating with the provided golang.design/x/hotkey/mainthread is possible.
+// For applications based on other GUI frameworks, one has to use their provided
+// ability to run the "(*Hotkey).Register" on the main thread. See the "./examples"
+// folder for more examples.
 package hotkey
 
 // Event represents a hotkey event
@@ -68,13 +42,19 @@ func New(mods []Modifier, key Key) *Hotkey {
 // Register registers a combination of hotkeys. If the hotkey has
 // registered. This function will invalidates the old registration
 // and overwrites its callback.
-func (hk *Hotkey) Register() error {
-	return hk.register()
-}
+//
+// For macOS, this method must be called on the main thread, and
+// an OS main event loop also must be running. This can be done when
+// collaborating with the golang.design/x/hotkey/mainthread package.
+func (hk *Hotkey) Register() error { return hk.register() }
 
-// Listen handles a hotkey event and triggers a call to fn.
-// The hotkey listen hook terminates when the context is canceled.
-func (hk *Hotkey) Listen() <-chan Event { return hk.out }
+// Keydown returns a channel that receives a signal when hotkey is triggered.
+func (hk *Hotkey) Keydown() <-chan Event { return hk.out }
+
+// Keyup returns a channel that receives a signal when the hotkey is released.
+func (hk *Hotkey) Keyup() <-chan Event {
+	panic("hotkey: unimplemented")
+}
 
 // Unregister unregisters the hotkey.
 func (hk *Hotkey) Unregister() error {

hotkey.go

@@ -24,8 +24,6 @@ import (
 	"errors"
 	"runtime/cgo"
 	"sync"
-
-	"golang.design/x/hotkey/mainthread"
 )
 
 // Hotkey is a combination of modifiers and key to trigger an event
@@ -53,9 +51,7 @@ func (hk *Hotkey) register() error {
 	}
 
 	var ret C.int
-	mainthread.Call(func() {
-		ret = C.registerHotKey(C.int(mod), C.int(hk.key), C.uintptr_t(h), &hk.hkref)
-	})
+	ret = C.registerHotKey(C.int(mod), C.int(hk.key), C.uintptr_t(h), &hk.hkref)
 	if ret == C.int(-1) {
 		return errors.New("failed to register the hotkey")
 	}

hotkey_darwin.go

@@ -15,6 +15,7 @@ import (
 	"time"
 
 	"golang.design/x/hotkey"
+	"golang.design/x/hotkey/mainthread"
 )
 
 // TestHotkey should always run success.
@@ -28,7 +29,9 @@ func TestHotkey(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), tt)
 	go func() {
 		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
-		if err := hk.Register(); err != nil {
+
+		var err error
+		if mainthread.Call(func() { err = hk.Register() }); err != nil {
 			t.Errorf("failed to register hotkey: %v", err)
 			return
 		}
@@ -38,15 +41,17 @@ func TestHotkey(t *testing.T) {
 				cancel()
 				done <- struct{}{}
 				return
-			case <-hk.Listen():
+			case <-hk.Keydown():
 				fmt.Println("triggered ctrl+shift+s")
 			}
 		}
 	}()
 
 	go func() {
 		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModOption}, hotkey.KeyS)
-		if err := hk.Register(); err != nil {
+
+		var err error
+		if mainthread.Call(func() { err = hk.Register() }); err != nil {
 			t.Errorf("failed to register hotkey: %v", err)
 			return
 		}
@@ -57,7 +62,7 @@ func TestHotkey(t *testing.T) {
 				cancel()
 				done <- struct{}{}
 				return
-			case <-hk.Listen():
+			case <-hk.Keydown():
 				fmt.Println("triggered ctrl+option+s")
 			}
 		}

hotkey_darwin_test.go

@@ -34,7 +34,7 @@ func TestHotkey(t *testing.T) {
 		select {
 		case <-ctx.Done():
 			return
-		case <-hk.Listen():
+		case <-hk.Keydown():
 			fmt.Println("triggered")
 		}
 	}

hotkey_linux_test.go

@@ -16,5 +16,5 @@ import (
 // The test cannot be run twice since the mainthread loop may not be terminated:
 // go test -v -count=1
 func TestMain(m *testing.M) {
-	mainthread.Run(func() { os.Exit(m.Run()) })
+	mainthread.Init(func() { os.Exit(m.Run()) })
 }