Skip to content

Commit af3c6af

Browse files
popaprozacpopaprozac
committed
update docs and readmes
1 parent 40117e6 commit af3c6af

File tree

6 files changed

+213
-125
lines changed

6 files changed

+213
-125
lines changed

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

+56-3
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,34 @@ app := application.New(application.Options{
2929
})
3030
```
3131

32+
### Creating the Service with Custom Options (Windows Only)
33+
34+
On Windows, you can customize the badge appearance with various options:
35+
36+
```go
37+
import "github.com/wailsapp/wails/v3/pkg/application"
38+
import "github.com/wailsapp/wails/v3/pkg/services/badge"
39+
import "image/color"
40+
41+
// Create a badge service with custom options
42+
options := badge.Options{
43+
TextColour: color.RGBA{255, 255, 255, 255}, // White text
44+
BackgroundColour: color.RGBA{0, 0, 255, 255}, // Green background
45+
FontName: "consolab.ttf", // Bold Consolas font
46+
FontSize: 20, // Font size for single character
47+
SmallFontSize: 14, // Font size for multiple characters
48+
}
49+
50+
badgeService := badge.NewWithOptions(options)
51+
52+
// Register the service with the application
53+
app := application.New(application.Options{
54+
Services: []application.Service{
55+
application.NewService(badgeService),
56+
},
57+
})
58+
```
59+
3260
## Badge Operations
3361

3462
### Setting a Badge
@@ -66,6 +94,8 @@ badgeService.RemoveBadge()
6694
- Automatically handle dark/light mode appearance
6795
- Use the standard macOS dock badge styling
6896
- Automatically handle label overflow
97+
- Do not support customization options (any options passed to NewWithOptions will be ignored)
98+
- Will display "●" as the default badge if an empty label is provided
6999

70100
</TabItem>
71101

@@ -75,9 +105,17 @@ badgeService.RemoveBadge()
75105

76106
- Are displayed as an overlay icon in the taskbar
77107
- Support text values
108+
- Allow customization of colors, font, and font sizes
78109
- Adapt to Windows theme settings
79110
- Require the application to have a window
80-
- Does not handle label overflow
111+
- Use smaller font size automatically for badges with multiple characters
112+
- Do not handle label overflow
113+
- Support the following customization options:
114+
- TextColour: Text color (default: white)
115+
- BackgroundColour: Badge background color (default: red)
116+
- FontName: Font file name (default: "segoeuib.ttf")
117+
- FontSize: Font size for single character (default: 18)
118+
- SmallFontSize: Font size for multiple characters (default: 14)
81119

82120
</TabItem>
83121

@@ -100,12 +138,18 @@ badgeService.RemoveBadge()
100138
- Numeric badges are most effective
101139
- On macOS, text badges should be brief
102140

141+
3. For Windows customization:
142+
- Ensure high contrast between text and background colors
143+
- Test with different text lengths as font size decreases with length
144+
- Use common system fonts to ensure availability
145+
103146
## API Reference
104147

105148
### Service Management
106149
| Method | Description |
107150
|--------------------------------------------|-------------------------------------------------------|
108-
| `New()` | Creates a new badge service |
151+
| `New()` | Creates a new badge service with default options |
152+
| `NewWithOptions(options Options)` | Creates a new badge service with custom option (Windows only, options are ignored on macOS) |
109153

110154
### Badge Operations
111155
| Method | Description |
@@ -115,4 +159,13 @@ badgeService.RemoveBadge()
115159

116160
### Structs and Types
117161

118-
This service doesn't define any specific structs or types beyond the standard error return types.
162+
```go
163+
// Options for customizing badge appearance (Windows only)
164+
type Options struct {
165+
TextColour color.RGBA // Color of the badge text
166+
BackgroundColour color.RGBA // Color of the badge background
167+
FontName string // Font file name (e.g., "segoeuib.ttf")
168+
FontSize int // Font size for single character
169+
SmallFontSize int // Font size for multiple characters
170+
}
171+
```

‎v3/examples/badge-custom/README.md

+57-36
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,80 @@
11
# Welcome to Your New Wails3 Project!
2+
Now that you have your project set up, it's time to explore the custom badge features that Wails3 offers on **Windows**.
23

3-
Congratulations on generating your Wails3 application! This README will guide you through the next steps to get your project up and running.
4+
## Exploring Custom Badge Features
45

5-
## Getting Started
6+
### Creating the Service with Custom Options (Windows Only)
67

7-
1. Navigate to your project directory in the terminal.
8+
On Windows, you can customize the badge appearance with various options:
89

9-
2. To run your application in development mode, use the following command:
10+
```go
11+
import "github.com/wailsapp/wails/v3/pkg/application"
12+
import "github.com/wailsapp/wails/v3/pkg/services/badge"
13+
import "image/color"
1014

11-
```
12-
wails3 dev
13-
```
15+
// Create a badge service with custom options
16+
options := badge.Options{
17+
TextColour: color.RGBA{255, 255, 255, 255}, // White text
18+
BackgroundColour: color.RGBA{0, 0, 255, 255}, // Green background
19+
FontName: "consolab.ttf", // Bold Consolas font
20+
FontSize: 20, // Font size for single character
21+
SmallFontSize: 14, // Font size for multiple characters
22+
}
1423

15-
This will start your application and enable hot-reloading for both frontend and backend changes.
24+
badgeService := badge.NewWithOptions(options)
1625

17-
3. To build your application for production, use:
26+
// Register the service with the application
27+
app := application.New(application.Options{
28+
Services: []application.Service{
29+
application.NewService(badgeService),
30+
},
31+
})
32+
```
1833

19-
```
20-
wails3 build
21-
```
34+
## Badge Operations
2235

23-
This will create a production-ready executable in the `build` directory.
36+
### Setting a Badge
2437

25-
## Exploring Wails3 Features
38+
Set a badge on the application tile/dock icon:
2639

27-
Now that you have your project set up, it's time to explore the features that Wails3 offers:
40+
**Go**
41+
```go
42+
// Set a default badge
43+
badgeService.SetBadge("")
2844

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.
45+
// Set a numeric badge
46+
badgeService.SetBadge("3")
3047

31-
2. **Run an example**: To run any of the examples, navigate to the example's directory and use:
48+
// Set a text badge
49+
badgeService.SetBadge("New")
50+
```
3251

33-
```
34-
go run .
35-
```
52+
**JS**
53+
```js
54+
import {SetBadge} from "../bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service";
3655

37-
Note: Some examples may be under development during the alpha phase.
56+
// Set a default badge
57+
SetBadge("")
3858

39-
3. **Explore the documentation**: Visit the [Wails3 documentation](https://v3.wails.io/) for in-depth guides and API references.
59+
// Set a numeric badge
60+
SetBadge("3")
4061

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).
62+
// Set a text badge
63+
SetBadge("New")
64+
```
4265

43-
## Project Structure
66+
### Removing a Badge
4467

45-
Take a moment to familiarize yourself with your project structure:
68+
Remove the badge from the application icon:
4669

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
70+
**Go**
71+
```go
72+
badgeService.RemoveBadge()
73+
```
5174

52-
## Next Steps
75+
**JS**
76+
```js
77+
import {RemoveBadge} from "../bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service";
5378

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.
79+
RemoveBadge()
80+
```

‎v3/examples/badge-custom/frontend/bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service.ts

+11-7
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,18 @@
88

99
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
1010
// @ts-ignore: Unused imports
11-
import {Call as $Call, Create as $Create} from "@wailsio/runtime";
11+
import { Call as $Call, CancellablePromise as $CancellablePromise, Create as $Create } from "@wailsio/runtime";
1212

13-
export function RemoveBadge(): Promise<void> & { cancel(): void } {
14-
let $resultPromise = $Call.ByID(2633565570) as any;
15-
return $resultPromise;
13+
/**
14+
* RemoveBadge removes the badge label from the application icon.
15+
*/
16+
export function RemoveBadge(): $CancellablePromise<void> {
17+
return $Call.ByID(2633565570);
1618
}
1719

18-
export function SetBadge(label: string): Promise<void> & { cancel(): void } {
19-
let $resultPromise = $Call.ByID(3052354152, label) as any;
20-
return $resultPromise;
20+
/**
21+
* SetBadge sets the badge label on the application icon.
22+
*/
23+
export function SetBadge(label: string): $CancellablePromise<void> {
24+
return $Call.ByID(3052354152, label);
2125
}

‎v3/examples/badge-custom/frontend/dist/assets/index-sXwpgKSV.js renamed to ‎v3/examples/badge-custom/frontend/dist/assets/index-edhLCYCH.js

+2-4
Original file line numberDiff line numberDiff line change
@@ -1324,12 +1324,10 @@ window._wails = window._wails || {};
13241324
window._wails.invoke = invoke;
13251325
invoke("wails:runtime:ready");
13261326
function RemoveBadge() {
1327-
let $resultPromise = ByID(2633565570);
1328-
return $resultPromise;
1327+
return ByID(2633565570);
13291328
}
13301329
function SetBadge(label) {
1331-
let $resultPromise = ByID(3052354152, label);
1332-
return $resultPromise;
1330+
return ByID(3052354152, label);
13331331
}
13341332
const setButton = document.getElementById("set");
13351333
const removeButton = document.getElementById("remove");

‎v3/examples/badge-custom/frontend/dist/index.html

+38-38
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,38 @@
1-
<!DOCTYPE html>
2-
<html lang="en">
3-
<head>
4-
<meta charset="UTF-8"/>
5-
<link rel="icon" type="image/svg+xml" href="/wails.png"/>
6-
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
7-
<link rel="stylesheet" href="/style.css"/>
8-
<title>Wails App</title>
9-
<script type="module" crossorigin src="/assets/index-sXwpgKSV.js"></script>
10-
</head>
11-
<body>
12-
<div class="container">
13-
<div>
14-
<a data-wml-openURL="https://wails.io">
15-
<img src="/wails.png" class="logo" alt="Wails logo"/>
16-
</a>
17-
<a data-wml-openURL="https://www.typescriptlang.org/">
18-
<img src="/typescript.svg" class="logo vanilla" alt="Typescript logo"/>
19-
</a>
20-
</div>
21-
<h1>Wails + Typescript</h1>
22-
<div class="result">Set a badge label below 👇</div>
23-
<div class="card">
24-
<div class="input-box" id="input">
25-
<input class="input" id="label" type="text" autocomplete="off"/>
26-
<button class="btn" id="set">Set</button>
27-
<button class="btn" id="remove">Remove</button>
28-
<button class="btn" id="set-go">Set using Go</button>
29-
<button class="btn" id="remove-go">Remove using Go</button>
30-
</div>
31-
</div>
32-
<div class="footer">
33-
<div><p>Click on the Wails logo to learn more</p></div>
34-
<div><p id="time">Listening for Time event...</p></div>
35-
</div>
36-
</div>
37-
</body>
38-
</html>
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8"/>
5+
<link rel="icon" type="image/svg+xml" href="/wails.png"/>
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
7+
<link rel="stylesheet" href="/style.css"/>
8+
<title>Wails App</title>
9+
<script type="module" crossorigin src="/assets/index-edhLCYCH.js"></script>
10+
</head>
11+
<body>
12+
<div class="container">
13+
<div>
14+
<a data-wml-openURL="https://wails.io">
15+
<img src="/wails.png" class="logo" alt="Wails logo"/>
16+
</a>
17+
<a data-wml-openURL="https://www.typescriptlang.org/">
18+
<img src="/typescript.svg" class="logo vanilla" alt="Typescript logo"/>
19+
</a>
20+
</div>
21+
<h1>Wails + Typescript</h1>
22+
<div class="result">Set a badge label below 👇</div>
23+
<div class="card">
24+
<div class="input-box" id="input">
25+
<input class="input" id="label" type="text" autocomplete="off"/>
26+
<button class="btn" id="set">Set</button>
27+
<button class="btn" id="remove">Remove</button>
28+
<button class="btn" id="set-go">Set using Go</button>
29+
<button class="btn" id="remove-go">Remove using Go</button>
30+
</div>
31+
</div>
32+
<div class="footer">
33+
<div><p>Click on the Wails logo to learn more</p></div>
34+
<div><p id="time">Listening for Time event...</p></div>
35+
</div>
36+
</div>
37+
</body>
38+
</html>

0 commit comments

Comments
 (0)