diff --git a/website/docs/gettingstarted/installation.mdx b/website/docs/gettingstarted/installation.mdx index 5cd767d95..797ebe158 100644 --- a/website/docs/gettingstarted/installation.mdx +++ b/website/docs/gettingstarted/installation.mdx @@ -47,7 +47,11 @@ import TabItem from "@theme/TabItem"; { label: "Linux", value: "Linux" }, ]} > - Coming Soon... + + Wails requires that the xcode command line tools are installed. This can be done by running:
+ + xcode-select --install + Wails requires that the WebView2{" "} runtime is installed. Some Windows installations will already have this installed. You can check using the{" "} diff --git a/website/docs/reference/cli.mdx b/website/docs/reference/cli.mdx index 8b2996281..6a033415b 100644 --- a/website/docs/reference/cli.mdx +++ b/website/docs/reference/cli.mdx @@ -74,6 +74,12 @@ Example: `wails build -clean -o myproject.exe` +:::info UPX on Apple Silicon + + There are [issues](https://github.com/upx/upx/issues/446) with using UPX with Apple Silicon. + +::: + ## doctor `wails doctor` will run diagnostics to ensure that your system is ready for development. diff --git a/website/docs/reference/menus.mdx b/website/docs/reference/menus.mdx index 96949456e..389a3eee1 100644 --- a/website/docs/reference/menus.mdx +++ b/website/docs/reference/menus.mdx @@ -79,6 +79,7 @@ type MenuItem struct { | Checked | bool | Adds check to item (Checkbox & Radio types) | | SubMenu | [\*Menu](#menu) | Sets the submenu | | Click | [Callback](#callback) | Callback function when menu clicked | +| Role | string | Defines a [role](#roles) for this menu item. Mac only for now. | ### Accelerator @@ -231,3 +232,19 @@ type CallbackData struct { The function is given a `CallbackData` struct which indicates which menu item triggered the callback. This is useful when using radio groups that may share a callback. + +### Role + +:::info Roles + + Roles are currently supported on Mac only. + +::: + +A menu item may have a role, which is essentially a pre-defined menu item. We currently support the following roles: + +| Role | Description | +| ---- | ----------- | +| AppMenuRole | The standard Mac application menu. Can be created using `menu.AppMenu()` | +| EditMenuRole | The standard Mac edit menu. Can be created using `menu.EditMenu()` | + diff --git a/website/docs/reference/options.mdx b/website/docs/reference/options.mdx index bc1e8df6e..d31648bae 100644 --- a/website/docs/reference/options.mdx +++ b/website/docs/reference/options.mdx @@ -43,6 +43,24 @@ func main() { WindowIsTranslucent: false, DisableWindowIcon: false, }, + Mac: &mac.Options{ + TitleBar: &mac.TitleBar{ + TitlebarAppearsTransparent: true, + HideTitle: false, + HideTitleBar: false, + FullSizeContent: false, + UseToolbar: false, + HideToolbarSeparator: true, + }, + Appearance: mac.NSAppearanceNameDarkAqua, + WebviewIsTransparent: true, + WindowIsTranslucent: false, + About: &mac.AboutInfo{ + Title: "My Application", + Message: "© 2021 Me", + Icon: icon, + }, + }, }) if err != nil { log.Fatal(err) @@ -281,3 +299,153 @@ Name: DisableWindowIcon Type: bool Setting this to true will remove the icon in the top left corner of the title bar. + + +## Mac Specific Options + +### TitleBar + +Name: TitleBar + +Type: [*mac.TitleBar](#titlebar-struct) + +The TitleBar struct provides the ability to configure the look and feel of the title bar. + +### Appearance + +Name: Appearance + +Type: [AppearanceType](#appearance-type) + +Appearance is used to set the style of your app in accordance with Apple's [NSAppearance](https://developer.apple.com/documentation/appkit/nsappearancename?language=objc) names. + +### WebviewIsTransparent + +Name: WebviewIsTransparent + +Type: bool + +Setting this to `true` will make the webview background transparent when an alpha value of `0` is used. +This means that if you use `rgba(0,0,0,0)`, the host window will show through. +Often combined with [WindowIsTranslucent](#WindowIsTranslucent) to make frosty-looking applications. + +### WindowIsTranslucent + +Name: WindowIsTranslucent + +Type: bool + +Setting this to `true` will make the window background translucent. Often combined +with [WebviewIsTransparent](#WebviewIsTransparent) to make frosty-looking applications. + +### About + +Name: About + +Type: [About](#about-struct) + +This configuration lets you set the title, message and icon for the "About" menu item in the app menu created by the "AppMenu" role. + +#### Titlebar struct + +The titlebar of the application can be customised by using the TitleBar options: + +```go +type TitleBar struct { + TitlebarAppearsTransparent bool + HideTitle bool + HideTitleBar bool + FullSizeContent bool + UseToolbar bool + HideToolbarSeparator bool +} +``` + +| Name | Description | +| ---- | ----------- | +| TitlebarAppearsTransparent | Makes the titlebar transparent. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindow/1419167-titlebarappearstransparent?language=objc) | +| HideTitle | Hides the title of the window. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindowtitlevisibility?language=objc) | +| HideTitleBar | Removes [NSWindowStyleMaskTitled](https://developer.apple.com/documentation/appkit/nswindowstylemask/nswindowstylemasktitled/) from the style mask | +| FullSizeContent | Makes the webview fill the entire window. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindowstylemask/nswindowstylemaskfullsizecontentview)| +| UseToolbar | Adds a default toolbar to the window. [Apple Docs](https://developer.apple.com/documentation/appkit/nstoolbar?language=objc) | +| HideToolbarSeparator | Removes the line beneath the toolbar. [Apple Docs](https://developer.apple.com/documentation/appkit/nstoolbar/1516954-showsbaselineseparator?language=objc) | + +Preconfigured titlebar settings are available: + +| Setting | Example | +| ------- | ------- | +|`mac.TitleBarDefault()` | ![](/img/reference/titlebar-default.png) | +|`mac.TitleBarHidden()` | ![](/img/reference/titlebar-hidden.png) | +|`mac.TitleBarHiddenInset()` | ![](/img/reference/titlebar-hidden-inset.png) | + +Example: +```go +Mac: &mac.Options{ + TitleBar: mac.TitleBarHiddenInset(), +} +``` + +Click [here](https://github.com/lukakerr/NSWindowStyles) for some inspiration on customising the titlebar. + +#### Appearance type + +You can specify the application's [appearance](https://developer.apple.com/documentation/appkit/nsappearance?language=objc). + +| Value | Description | +| --------------- | ------------------ | +| DefaultAppearance | DefaultAppearance uses the default system value | +| NSAppearanceNameAqua | The standard light system appearance | +| NSAppearanceNameDarkAqua | The standard dark system appearance | +| NSAppearanceNameVibrantLight | The light vibrant appearance | +| NSAppearanceNameAccessibilityHighContrastAqua | A high-contrast version of the standard light system appearance | +| NSAppearanceNameAccessibilityHighContrastDarkAqua | A high-contrast version of the standard dark system appearance | +| NSAppearanceNameAccessibilityHighContrastVibrantLight | A high-contrast version of the light vibrant appearance | +| NSAppearanceNameAccessibilityHighContrastVibrantDark | A high-contrast version of the dark vibrant appearance | + +Example: +```go +Mac: &mac.Options{ + Appearance: mac.NSAppearanceNameDarkAqua, +} +``` + +#### About struct + +```go +type AboutInfo struct { + Title string + Message string + Icon []byte +} +``` +If these settings are provided, an "About" menu item will appear in the app menu (when using the `AppMenu` role). +Given this configuration: +```go +//go:embed build/appicon.png +var icon []byte + +func main() { + err := wails.Run(&options.App{ + ... + Mac: &mac.Options{ + About: &mac.AboutInfo{ + Title: "My Application", + Message: "© 2021 Me", + Icon: icon, + }, + }, + }) +``` +The "About" menu item will appear in the app menu: + +
+ +
+
+ +When clicked, that will open an about message box: + +
+ +
+
diff --git a/website/static/img/reference/about-dialog.png b/website/static/img/reference/about-dialog.png new file mode 100644 index 000000000..8af3ef91e Binary files /dev/null and b/website/static/img/reference/about-dialog.png differ diff --git a/website/static/img/reference/about-menu.png b/website/static/img/reference/about-menu.png new file mode 100644 index 000000000..6ac7166e9 Binary files /dev/null and b/website/static/img/reference/about-menu.png differ diff --git a/website/static/img/reference/titlebar-default.png b/website/static/img/reference/titlebar-default.png new file mode 100644 index 000000000..8204d3f97 Binary files /dev/null and b/website/static/img/reference/titlebar-default.png differ diff --git a/website/static/img/reference/titlebar-hidden-inset.png b/website/static/img/reference/titlebar-hidden-inset.png new file mode 100644 index 000000000..b3161367d Binary files /dev/null and b/website/static/img/reference/titlebar-hidden-inset.png differ diff --git a/website/static/img/reference/titlebar-hidden.png b/website/static/img/reference/titlebar-hidden.png new file mode 100644 index 000000000..c68db0594 Binary files /dev/null and b/website/static/img/reference/titlebar-hidden.png differ