Merge branch 'master' of github:magicmonkey/go-streamdeck

Author: magicmonkey

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to Go-Streamdeck
+
+All issues, pull requests and other feedback are very welcome in this project. Please do take the time to read the information below, and get involved!
+
+- [Use Go-Streamdeck From Source](#use-go-streamdeck-from-source)
+- [Share Issues, Bugs and Feature Requests](#share-issues-bugs-and-feature-requests)
+- [Submit a Patch or Pull Request](#submit-a-patch-or-pull-request)
+- [Try the Examples](#try-the-examples)
+- [Usage in Other Projects](#usage-in-other-projects)
+
+## Use Go-Streamdeck From Source
+
+To use the `master` branch, another branch, or a branch in your own fork, you can use the `replace` syntax in your `go.mod` file. For more information and an example try this [excellent blog post from Pam Selle](https://thewebivore.com/using-replace-in-go-mod-to-point-to-your-local-module/).
+
+## Share Issues, Bugs and Feature Requests
+
+Go ahead and open an issue, choosing whether you are making a bug report, or a feature request. If it's both, or neither, just pick one! The only difference is the template you are prompted to complete. It's fine to ask questions and support queries by opening an issue on this repository too.
+
+## Submit a Patch or Pull Request
+
+You will need to fork the repository to offer patches. Please make sure your master branch is up to date, then start a new branch, named for the feature/bugfix it contains.
+
+For large changes, please open an issue for discussion so that we know we are not duplicating work or working on a feature that won't be accepted at the end of the process.
+
+## Try the Examples
+
+The `examples/` directory has a series of examples that may be useful in your own applications. Try these out to see the various features in action.
+
+Please open an issue to update us for which operating systems and StreamDeck combinations are working well for you!
+
+## Usage in Other Projects
+
+You are very welcome to use this project within the terms of the license. We would love to have you in our showcase, please open a pull request to update the `README.md` file with a link to your project.

README.md

@@ -6,6 +6,13 @@ A Go interface to an Elgato Streamdeck (currently works with the 32-button XL on
 
 _Designed for and tested with Ubuntu, Go 1.13+ and a Streamdeck XL. Images are the wrong size for other streamdecks; bug reports and patches are welcome!_
 
+- [Installation](#installation)
+- [Usage](#usage)
+  * [Example high-level usage](#example-high-level-usage)
+  * [Example low-level usage](#example-low-level-usage)
+- [Showcase](#showcase)
+- [Contributions](#contributions)
+
 ## Installation
 
 Either include the library in your project or install it with the following command:
@@ -109,6 +116,14 @@ func main() {
 
 The program runs for 20 seconds and then exits.
 
+## Showcase
+
+Projects using this library (pull request to add yours!)
+
+* [Streamdeck tricks](https://github.com/lornajane/streamdeck-tricks)
+
 ## Contributions
 
 This is a very new project but all feedback, comments, questions and patches are more than welcome. Please get in touch by opening an issue, it would be good to hear who is using the project and how things are going.
+
+For more, see [CONTRIBUTING.md](CONTRIBUTING.md).

buttons/colour.go

@@ -8,13 +8,15 @@ import (
 	streamdeck "github.com/magicmonkey/go-streamdeck"
 )
 
+// ColourButton represents a button which is a solid block of a single colour
 type ColourButton struct {
 	colour        color.Color
 	updateHandler func(streamdeck.Button)
 	btnIndex      int
 	actionHandler streamdeck.ButtonActionHandler
 }
 
+// GetImageForButton is the interface implemention to get the button's image as an image.Image
 func (btn *ColourButton) GetImageForButton() image.Image {
 	ButtonSize := 96
 	img := image.NewRGBA(image.Rect(0, 0, ButtonSize, ButtonSize))
@@ -23,33 +25,43 @@ func (btn *ColourButton) GetImageForButton() image.Image {
 	return img
 }
 
+// SetButtonIndex is the interface implemention to set which button on the Streamdeck this is
 func (btn *ColourButton) SetButtonIndex(btnIndex int) {
 	btn.btnIndex = btnIndex
 }
 
+// GetButtonIndex is the interface implemention to get which button on the Streamdeck this is
 func (btn *ColourButton) GetButtonIndex() int {
 	return btn.btnIndex
 }
 
+// SetColour allows the colour for the button to be changed on the fly
 func (btn *ColourButton) SetColour(colour color.Color) {
 	btn.colour = colour
 	btn.updateHandler(btn)
 }
 
+// RegisterUpdateHandler is the interface implemention to let the engine give this button a callback to
+// use to request that the button image is updated on the Streamdeck.
 func (btn *ColourButton) RegisterUpdateHandler(f func(streamdeck.Button)) {
 	btn.updateHandler = f
 }
 
+// SetActionHandler allows a ButtonActionHandler implementation to be
+// set on this button, so that something can happen when the button is pressed.
 func (btn *ColourButton) SetActionHandler(a streamdeck.ButtonActionHandler) {
 	btn.actionHandler = a
 }
 
+// Pressed is the interface implementation for letting the engine notify that the button has been
+// pressed.  This hands-off to the specified ButtonActionHandler if it has been set.
 func (btn *ColourButton) Pressed() {
 	if btn.actionHandler != nil {
 		btn.actionHandler.Pressed(btn)
 	}
 }
 
+// NewColourButton creates a new ColourButton of the specified colour
 func NewColourButton(colour color.Color) *ColourButton {
 	btn := &ColourButton{colour: colour}
 	return btn

buttons/imagefile.go

@@ -8,6 +8,8 @@ import (
 	streamdeck "github.com/magicmonkey/go-streamdeck"
 )
 
+// ImageFileButton represents a button with an image on it, where the image is loaded
+// from a file.
 type ImageFileButton struct {
 	filePath      string
 	img           image.Image
@@ -16,21 +18,25 @@ type ImageFileButton struct {
 	actionHandler streamdeck.ButtonActionHandler
 }
 
+// GetImageForButton is the interface implemention to get the button's image as an image.Image
 func (btn *ImageFileButton) GetImageForButton() image.Image {
 	// TODO base the 96 on the image bounds
 	newimg := image.NewRGBA(image.Rect(0, 0, 96, 96))
 	draw.Draw(newimg, newimg.Bounds(), btn.img, image.Point{0, 0}, draw.Src)
 	return newimg
 }
 
+// SetButtonIndex is the interface implemention to set which button on the Streamdeck this is
 func (btn *ImageFileButton) SetButtonIndex(btnIndex int) {
 	btn.btnIndex = btnIndex
 }
 
+// GetButtonIndex is the interface implemention to get which button on the Streamdeck this is
 func (btn *ImageFileButton) GetButtonIndex() int {
 	return btn.btnIndex
 }
 
+// SetFilePath allows the image file to be changed on the fly
 func (btn *ImageFileButton) SetFilePath(filePath string) error {
 	btn.filePath = filePath
 	err := btn.loadImage()
@@ -64,20 +70,27 @@ func (btn *ImageFileButton) loadImage() error {
 	return nil
 }
 
+// RegisterUpdateHandler is the interface implemention to let the engine give this button a callback to
+// use to request that the button image is updated on the Streamdeck.
 func (btn *ImageFileButton) RegisterUpdateHandler(f func(streamdeck.Button)) {
 	btn.updateHandler = f
 }
 
+// SetActionHandler allows a ButtonActionHandler implementation to be
+// set on this button, so that something can happen when the button is pressed.
 func (btn *ImageFileButton) SetActionHandler(a streamdeck.ButtonActionHandler) {
 	btn.actionHandler = a
 }
 
+// Pressed is the interface implementation for letting the engine notify that the button has been
+// pressed.  This hands-off to the specified ButtonActionHandler if it has been set.
 func (btn *ImageFileButton) Pressed() {
 	if btn.actionHandler != nil {
 		btn.actionHandler.Pressed(btn)
 	}
 }
 
+// NewImageFileButton creates a new ImageFileButton with the specified image on it
 func NewImageFileButton(filePath string) (*ImageFileButton, error) {
 	btn := &ImageFileButton{filePath: filePath}
 	err := btn.loadImage()

buttons/text.go

@@ -12,6 +12,7 @@ import (
 	streamdeck "github.com/magicmonkey/go-streamdeck"
 )
 
+// TextButton represents a button with text on it
 type TextButton struct {
 	label            string
 	textColour       color.Color
@@ -21,53 +22,71 @@ type TextButton struct {
 	actionHandler    streamdeck.ButtonActionHandler
 }
 
+// GetImageForButton is the interface implemention to get the button's image as an image.Image
 func (btn *TextButton) GetImageForButton() image.Image {
 	img := getImageWithText(btn.label, btn.textColour, btn.backgroundColour)
 	return img
 }
 
+// SetButtonIndex is the interface implemention to set which button on the Streamdeck this is
 func (btn *TextButton) SetButtonIndex(btnIndex int) {
 	btn.btnIndex = btnIndex
 }
 
+// GetButtonIndex is the interface implemention to get which button on the Streamdeck this is
 func (btn *TextButton) GetButtonIndex() int {
 	return btn.btnIndex
 }
 
+// SetText allows the text on the button to be changed on the fly
 func (btn *TextButton) SetText(label string) {
 	btn.label = label
 	btn.updateHandler(btn)
 }
 
+// SetTextColour allows the colour of the text on the button to be changed on the fly
 func (btn *TextButton) SetTextColour(textColour color.Color) {
 	btn.textColour = textColour
 	btn.updateHandler(btn)
 }
 
+// SetBackgroundColor allows the background colour on the button to be changed on the fly
 func (btn *TextButton) SetBackgroundColor(backgroundColour color.Color) {
 	btn.backgroundColour = backgroundColour
 	btn.updateHandler(btn)
 }
 
+// RegisterUpdateHandler is the interface implemention to let the engine give this button a callback to
+// use to request that the button image is updated on the Streamdeck.
 func (btn *TextButton) RegisterUpdateHandler(f func(streamdeck.Button)) {
 	btn.updateHandler = f
 }
 
+// SetActionHandler allows a ButtonActionHandler implementation to be
+// set on this button, so that something can happen when the button is pressed.
 func (btn *TextButton) SetActionHandler(a streamdeck.ButtonActionHandler) {
 	btn.actionHandler = a
 }
 
+// Pressed is the interface implementation for letting the engine notify that the button has been
+// pressed.  This hands-off to the specified ButtonActionHandler if it has been set.
 func (btn *TextButton) Pressed() {
 	if btn.actionHandler != nil {
 		btn.actionHandler.Pressed(btn)
 	}
 }
 
+// NewTextButton creates a new TextButton with the specified text on it, in white on a black
+// background.  The text will be set on a single line, and auto-sized to fill the button as best
+// as possible.
 func NewTextButton(label string) *TextButton {
 	btn := NewTextButtonWithColours(label, color.White, color.Black)
 	return btn
 }
 
+// NewTextButtonWithColours creates a new TextButton with the specified text on it, in the specified
+// text and background colours.  The text will be set on a single line, and auto-sized to fill the
+// button as best as possible.
 func NewTextButtonWithColours(label string, textColour color.Color, backgroundColour color.Color) *TextButton {
 	btn := &TextButton{label: label, textColour: textColour, backgroundColour: backgroundColour}
 	return btn
@@ -92,17 +111,17 @@ func getImageWithText(text string, textColour color.Color, backgroundColour colo
 		}
 	}
 
-	src_img := image.NewUniform(textColour)
+	srcImg := image.NewUniform(textColour)
 
-	dst_img := image.NewRGBA(image.Rect(0, 0, ButtonSize, ButtonSize))
-	draw.Draw(dst_img, dst_img.Bounds(), image.NewUniform(backgroundColour), image.Point{0, 0}, draw.Src)
+	dstImg := image.NewRGBA(image.Rect(0, 0, ButtonSize, ButtonSize))
+	draw.Draw(dstImg, dstImg.Bounds(), image.NewUniform(backgroundColour), image.Point{0, 0}, draw.Src)
 
 	c := freetype.NewContext()
 	c.SetFont(myfont)
-	c.SetDst(dst_img)
-	c.SetSrc(src_img)
+	c.SetDst(dstImg)
+	c.SetSrc(srcImg)
 	c.SetFontSize(size)
-	c.SetClip(dst_img.Bounds())
+	c.SetClip(dstImg.Bounds())
 
 	x := int((96 - width) / 2) // Horizontally centre text
 	y := int(50 + (size / 3))  // Fudged vertical centre, erm, very "heuristic"
@@ -115,14 +134,14 @@ func getImageWithText(text string, textColour color.Color, backgroundColour colo
 		fmt.Println(textWidth)
 
 		f := &font.Drawer{
-			Dst:  dst_img,
+			Dst:  dstImg,
 			Src:  src_img,
 			Face: basicfont.Face7x13,
 			Dot:  fixed.Point26_6{fixed.Int26_6(x * 64), fixed.Int26_6(y * 64)},
 		}
 		f.DrawString(text)
 	*/
-	return dst_img
+	return dstImg
 }
 
 func getTextWidth(text string, size float64) int {

examples/client/client.go

@@ -19,47 +19,58 @@ func main() {
 	}
 	fmt.Printf("Found device [%s]\n", sd.GetName())
 
+	// Button in position 2, changes to "Bye!" at the end of the program
+	// When pressed, this prints "You pressed me" to the terminal
 	myButton := buttons.NewTextButton("Hi world")
 	myButton.SetActionHandler(&actionhandlers.TextPrintAction{Label: "You pressed me"})
 	sd.AddButton(2, myButton)
 
+	// Button in position 3, prints "5" to the terminal when pressed
 	myOtherButton := buttons.NewTextButton("4")
 	myOtherButton.SetActionHandler(&actionhandlers.NumberPrintAction{Number: 5})
 	sd.AddButton(3, myOtherButton)
 
+	// Button in position 7 (top right on Streamdeck XL), says 7
+	// When pressed, changes to display "8"
 	myNextButton := buttons.NewTextButton("7")
 	myNextButton.SetActionHandler(&actionhandlers.TextLabelChangeAction{NewLabel: "8"})
 	sd.AddButton(7, myNextButton)
 
+	// Image button, no action handler
 	anotherButton, err := buttons.NewImageFileButton("examples/test/play.jpg")
 	if err != nil {
 		panic(err)
 	}
 	sd.AddButton(9, anotherButton)
 
+	// Yellow button, no action handler but it goes to blue at the end of the program
 	cButton := buttons.NewColourButton(color.RGBA{255, 255, 0, 255})
 	sd.AddButton(26, cButton)
 
+	// One button, two actions (uses ChainedAction)
+	// Purple button, prints to the console and turns red when pressed
 	multiActionButton := buttons.NewColourButton(color.RGBA{255, 0, 255, 255})
 	thisActionHandler := &actionhandlers.ChainedAction{}
 	thisActionHandler.AddAction(&actionhandlers.TextPrintAction{Label: "Purple press"})
 	thisActionHandler.AddAction(&actionhandlers.ColourChangeAction{NewColour: color.RGBA{255, 0, 0, 255}})
 	multiActionButton.SetActionHandler(thisActionHandler)
 	sd.AddButton(27, multiActionButton)
 
+	// Text button, gets a red highlight after 2 seconds, then a green
+	// highlight after another 2 seconds
 	decoratedButton := buttons.NewTextButton("ABC")
 	sd.AddButton(19, decoratedButton)
-
 	time.Sleep(2 * time.Second)
 	decorator1 := decorators.NewBorder(10, color.RGBA{0, 255, 0, 255})
 	sd.SetDecorator(19, decorator1)
 	time.Sleep(2 * time.Second)
 	decorator2 := decorators.NewBorder(5, color.RGBA{255, 0, 0, 255})
 	sd.SetDecorator(19, decorator2)
-
 	time.Sleep(2 * time.Second)
 
+	// When this button says "Bye!", the program ends
 	myButton.SetText("Bye!")
+	// When this button goes blue, the program ends
 	cButton.SetColour(color.RGBA{0, 255, 255, 255})
 	sd.UnsetDecorator(19)
 }