Skip to content

Commit efbb8bf

Browse files
popaprozacpopaprozac
committed
add example, update docs, update changelog
1 parent 610ca03 commit efbb8bf

36 files changed

+1568
-19
lines changed

‎docs/src/content/docs/changelog.mdx

+3-2
Original file line numberDiff line numberDiff line change
@@ -78,9 +78,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7878
- Gin support by [Lea Anthony](https://github.com/leaanthony) in [PR](https://github.com/wailsapp/wails/pull/3537) based on the original work of [@AnalogJ](https://github.com/AnalogJ) in PR[https://github.com/wailsapp/wails/pull/3537]
7979
- Fix auto save and password auto save always enabled by [@oSethoum](https://github.com/osethoum) in [#4134](https://github.com/wailsapp/wails/pull/4134)
8080
- Add `SetMenu()` on window to allow for setting a menu on a window by [@leaanthony](https://github.com/leaanthony)
81-
- Add Notification support by [@popaprozac] in [#4098](https://github.com/wailsapp/wails/pull/4098)
81+
- Add Notification support by [@popaprozac](https://github.com/popaprozac) in [#4098](https://github.com/wailsapp/wails/pull/4098)
8282
-  Add File Association support for mac by [@wimaha](https://github.com/wimaha) in [#4177](https://github.com/wailsapp/wails/pull/4177)
8383
- Add `wails3 tool version` for semantic version bumping by [@leaanthony](https://github.com/leaanthony)
84+
- Add badging support for macOS and Windows by [@popaprozac](https://github.com/popaprozac) in [#]()
8485
### Fixed
8586

8687
- Fixed Windows+Linux Edit Menu issues by [@leaanthony](https://github.com/leaanthony) in [#3f78a3a](https://github.com/wailsapp/wails/commit/3f78a3a8ce7837e8b32242c8edbbed431c68c062)
@@ -153,7 +154,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
153154
- Built-in service creation functions with options are now consistently called `NewWithConfig` by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
154155
- `Select` method on `sqlite` service is now named `Query` for consistency with Go APIs by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
155156
- Templates: moved runtime to "dependencies", organized package.json files by [@IanVS](https://github.com/IanVS) in [#4133](https://github.com/wailsapp/wails/pull/4133)
156-
- Creates and ad-hoc signs app bundles in dev to enable certain macOS APIs by [@popaprozac] in [#4171](https://github.com/wailsapp/wails/pull/4171)
157+
- Creates and ad-hoc signs app bundles in dev to enable certain macOS APIs by [@popaprozac](https://github.com/popaprozac) in [#4171](https://github.com/wailsapp/wails/pull/4171)
157158

158159
## v3.0.0-alpha.9 - 2025-01-13
159160

‎docs/src/content/docs/learn/badges.mdx

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Badges
3+
---
4+
5+
import { Tabs, TabItem } from "@astrojs/starlight/components";
6+
7+
## Introduction
8+
9+
Wails provides a cross-platform badge service for desktop applications. This service allows you to display badges on your application tile or dock icon, which is useful for indicating unread messages, notifications, or other status information.
10+
11+
## Basic Usage
12+
13+
### Creating the Service
14+
15+
First, initialize the badge service:
16+
17+
```go
18+
import "github.com/wailsapp/wails/v3/pkg/application"
19+
import "github.com/wailsapp/wails/v3/services/badge"
20+
21+
// Create a new badge service
22+
badgeService := badge.New()
23+
24+
// Register the service with the application
25+
app := application.New(application.Options{
26+
Services: []application.Service{
27+
application.NewService(badgeService),
28+
},
29+
})
30+
```
31+
32+
## Badge Operations
33+
34+
### Setting a Badge
35+
36+
Set a badge on the application tile/dock icon:
37+
38+
```go
39+
// Set a numeric badge
40+
badgeService.SetBadge("3")
41+
42+
// Set a text badge
43+
badgeService.SetBadge("New")
44+
45+
// Set a symbol badge
46+
badgeService.SetBadge("●")
47+
```
48+
49+
### Removing a Badge
50+
51+
Remove the badge from the application icon:
52+
53+
```go
54+
badgeService.RemoveBadge()
55+
56+
// or
57+
58+
// Set an empty string
59+
badgeService.SetBadge("")
60+
```
61+
62+
## Platform Considerations
63+
64+
<Tabs>
65+
<TabItem label="macOS" icon="fa-brands:apple">
66+
67+
On macOS, badges:
68+
69+
- Are displayed directly on the dock icon
70+
- Support both text and numeric values
71+
- Automatically handle dark/light mode appearance
72+
- Use the standard macOS dock badge styling
73+
74+
</TabItem>
75+
76+
<TabItem label="Windows" icon="fa-brands:windows">
77+
78+
On Windows, badges:
79+
80+
- Are displayed as an overlay icon in the taskbar
81+
- Currently implemented as a red circle with a white center
82+
- Do not currently support displaying text or numbers
83+
- Adapt to Windows theme settings
84+
- Require the application to have a window
85+
86+
</TabItem>
87+
88+
<TabItem label="Linux" icon="fa-brands:linux">
89+
90+
On Linux:
91+
92+
- Badge functionality is not available
93+
94+
</TabItem>
95+
</Tabs>
96+
97+
## Best Practices
98+
99+
1. Use badges sparingly:
100+
- Too many badge updates can distract users
101+
- Reserve badges for important notifications
102+
103+
2. Keep badge text short:
104+
- Numeric badges are most effective
105+
- On macOS, text badges should be brief
106+
107+
## API Reference
108+
109+
### Service Management
110+
| Method | Description |
111+
|--------------------------------------------|-------------------------------------------------------|
112+
| `New()` | Creates a new badge service |
113+
114+
### Badge Operations
115+
| Method | Description |
116+
|----------------------------------------------|------------------------------------------------------------|
117+
| `SetBadge(label string) error` | Sets a badge with the specified label |
118+
| `RemoveBadge() error` | Removes the badge from the application icon |
119+
120+
### Structs and Types
121+
122+
This service doesn't define any specific structs or types beyond the standard error return types.

‎v3/examples/badge/README.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Welcome to Your New Wails3 Project!
2+
3+
Congratulations on generating your Wails3 application! This README will guide you through the next steps to get your project up and running.
4+
5+
## Getting Started
6+
7+
1. Navigate to your project directory in the terminal.
8+
9+
2. To run your application in development mode, use the following command:
10+
11+
```
12+
wails3 dev
13+
```
14+
15+
This will start your application and enable hot-reloading for both frontend and backend changes.
16+
17+
3. To build your application for production, use:
18+
19+
```
20+
wails3 build
21+
```
22+
23+
This will create a production-ready executable in the `build` directory.
24+
25+
## Exploring Wails3 Features
26+
27+
Now that you have your project set up, it's time to explore the features that Wails3 offers:
28+
29+
1. **Check out the examples**: The best way to learn is by example. Visit the `examples` directory in the `v3/examples` directory to see various sample applications.
30+
31+
2. **Run an example**: To run any of the examples, navigate to the example's directory and use:
32+
33+
```
34+
go run .
35+
```
36+
37+
Note: Some examples may be under development during the alpha phase.
38+
39+
3. **Explore the documentation**: Visit the [Wails3 documentation](https://v3.wails.io/) for in-depth guides and API references.
40+
41+
4. **Join the community**: Have questions or want to share your progress? Join the [Wails Discord](https://discord.gg/JDdSxwjhGf) or visit the [Wails discussions on GitHub](https://github.com/wailsapp/wails/discussions).
42+
43+
## Project Structure
44+
45+
Take a moment to familiarize yourself with your project structure:
46+
47+
- `frontend/`: Contains your frontend code (HTML, CSS, JavaScript/TypeScript)
48+
- `main.go`: The entry point of your Go backend
49+
- `app.go`: Define your application structure and methods here
50+
- `wails.json`: Configuration file for your Wails project
51+
52+
## Next Steps
53+
54+
1. Modify the frontend in the `frontend/` directory to create your desired UI.
55+
2. Add backend functionality in `main.go`.
56+
3. Use `wails3 dev` to see your changes in real-time.
57+
4. When ready, build your application with `wails3 build`.
58+
59+
Happy coding with Wails3! If you encounter any issues or have questions, don't hesitate to consult the documentation or reach out to the Wails community.

‎v3/examples/badge/Taskfile.yml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
version: '3'
2+
3+
includes:
4+
common: ./build/Taskfile.yml
5+
windows: ./build/windows/Taskfile.yml
6+
darwin: ./build/darwin/Taskfile.yml
7+
linux: ./build/linux/Taskfile.yml
8+
9+
vars:
10+
APP_NAME: "badge"
11+
BIN_DIR: "bin"
12+
VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'
13+
14+
tasks:
15+
build:
16+
summary: Builds the application
17+
cmds:
18+
- task: "{{OS}}:build"
19+
20+
package:
21+
summary: Packages a production build of the application
22+
cmds:
23+
- task: "{{OS}}:package"
24+
25+
run:
26+
summary: Runs the application
27+
cmds:
28+
- task: "{{OS}}:run"
29+
30+
dev:
31+
summary: Runs the application in development mode
32+
cmds:
33+
- wails3 dev -config ./build/config.yml -port {{.VITE_PORT}}
34+

‎v3/examples/badge/build/Taskfile.yml

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
version: '3'
2+
3+
tasks:
4+
go:mod:tidy:
5+
summary: Runs `go mod tidy`
6+
internal: true
7+
cmds:
8+
- go mod tidy
9+
10+
install:frontend:deps:
11+
summary: Install frontend dependencies
12+
dir: frontend
13+
sources:
14+
- package.json
15+
- package-lock.json
16+
generates:
17+
- node_modules/*
18+
preconditions:
19+
- sh: npm version
20+
msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/"
21+
cmds:
22+
- npm install
23+
24+
build:frontend:
25+
label: build:frontend (PRODUCTION={{.PRODUCTION}})
26+
summary: Build the frontend project
27+
dir: frontend
28+
sources:
29+
- "**/*"
30+
generates:
31+
- dist/**/*
32+
deps:
33+
- task: install:frontend:deps
34+
- task: generate:bindings
35+
vars:
36+
BUILD_FLAGS:
37+
ref: .BUILD_FLAGS
38+
cmds:
39+
- npm run {{.BUILD_COMMAND}} -q
40+
env:
41+
PRODUCTION: '{{.PRODUCTION | default "false"}}'
42+
vars:
43+
BUILD_COMMAND: '{{if eq .PRODUCTION "true"}}build{{else}}build:dev{{end}}'
44+
45+
46+
generate:bindings:
47+
label: generate:bindings (BUILD_FLAGS={{.BUILD_FLAGS}})
48+
summary: Generates bindings for the frontend
49+
deps:
50+
- task: go:mod:tidy
51+
sources:
52+
- "**/*.[jt]s"
53+
- exclude: frontend/**/*
54+
- frontend/bindings/**/* # Rerun when switching between dev/production mode causes changes in output
55+
- "**/*.go"
56+
- go.mod
57+
- go.sum
58+
generates:
59+
- frontend/bindings/**/*
60+
cmds:
61+
- wails3 generate bindings -f '{{.BUILD_FLAGS}}' -clean=true -ts
62+
63+
generate:icons:
64+
summary: Generates Windows `.ico` and Mac `.icns` files from an image
65+
dir: build
66+
sources:
67+
- "appicon.png"
68+
generates:
69+
- "darwin/icons.icns"
70+
- "windows/icon.ico"
71+
cmds:
72+
- wails3 generate icons -input appicon.png -macfilename darwin/icons.icns -windowsfilename windows/icon.ico
73+
74+
dev:frontend:
75+
summary: Runs the frontend in development mode
76+
dir: frontend
77+
deps:
78+
- task: install:frontend:deps
79+
cmds:
80+
- npm run dev -- --port {{.VITE_PORT}} --strictPort
81+
82+
update:build-assets:
83+
summary: Updates the build assets
84+
dir: build
85+
cmds:
86+
- wails3 update build-assets -name "{{.APP_NAME}}" -binaryname "{{.APP_NAME}}" -config config.yml -dir .

‎v3/examples/badge/build/appicon.png

130 KB
Loading

‎v3/examples/badge/build/config.yml

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# This file contains the configuration for this project.
2+
# When you update `info` or `fileAssociations`, run `wails3 task common:update:build-assets` to update the assets.
3+
# Note that this will overwrite any changes you have made to the assets.
4+
version: '3'
5+
6+
# This information is used to generate the build assets.
7+
info:
8+
companyName: "My Company" # The name of the company
9+
productName: "My Product" # The name of the application
10+
productIdentifier: "com.mycompany.myproduct" # The unique product identifier
11+
description: "A program that does X" # The application description
12+
copyright: "(c) 2025, My Company" # Copyright text
13+
comments: "Some Product Comments" # Comments
14+
version: "0.0.1" # The application version
15+
16+
# Dev mode configuration
17+
dev_mode:
18+
root_path: .
19+
log_level: warn
20+
debounce: 1000
21+
ignore:
22+
dir:
23+
- .git
24+
- node_modules
25+
- frontend
26+
- bin
27+
file:
28+
- .DS_Store
29+
- .gitignore
30+
- .gitkeep
31+
watched_extension:
32+
- "*.go"
33+
git_ignore: true
34+
executes:
35+
- cmd: wails3 task common:install:frontend:deps
36+
type: once
37+
- cmd: wails3 task common:dev:frontend
38+
type: background
39+
- cmd: go mod tidy
40+
type: blocking
41+
- cmd: wails3 task build
42+
type: blocking
43+
- cmd: wails3 task run
44+
type: primary
45+
46+
# File Associations
47+
# More information at: https://v3.wails.io/noit/done/yet
48+
fileAssociations:
49+
# - ext: wails
50+
# name: Wails
51+
# description: Wails Application File
52+
# iconName: wailsFileIcon
53+
# role: Editor
54+
# - ext: jpg
55+
# name: JPEG
56+
# description: Image File
57+
# iconName: jpegFileIcon
58+
# role: Editor
59+
# mimeType: image/jpeg # (optional)
60+
61+
# Other data
62+
other:
63+
- name: My Other Data

0 commit comments

Comments
 (0)