Desktop.Window (Desktop v1.1.0) View Source

Defines a Desktop Window.

The window hosts a Phoenix Endpoint and displays its content. It should be part of a supervision tree and is the main interface to interact with your application.

In total the window is doing:

Displaying the endpoint content
Hosting and starting an optional menu bar
Controlling a taskbar icon if present

The Window

You can add the Window to your own Supervision tree:

children = [{
  Desktop.Window,
  [
    app: :your_app,
    id: YourAppWindow,
    title: "Your App Title",
    size: {600, 500},
    icon: "icon.png",
    menubar: YourApp.MenuBar,
    icon_menu: YourApp.Menu,
    url: fn -> YourAppWeb.Router.Helpers.live_url(YourAppWeb.Endpoint, YourAppWeb.YourAppLive) end
  ]
}]

Window configuration

In order to change the appearance of the application window these options can be defined:

:app - your app name within which the Window is running.
:id - an atom identifying the window. Can later be used to control the window using the functions of this module.
:title - the window title that will be show initially. The window title can be set later using set_title/2.
:size - the initial windows size in pixels {width, height}.
:hidden - whether the window should be initially hidden defaults to false,
```
        but is ignored on mobile platforms
```
Possible values are:
- false - Show the window on startup (default)
- true - Don't show the window on startup
:icon - an icon file name that will be used as taskbar and window icon. Supported formats are png files
:menubar - an optional MenuBar module that will be rendered as the windows menu bar when given.
:icon_menu - an optional MenuBar module that will be rendered as menu onclick on the taskbar icon.
:url - a callback to the initial (default) url to show in the window.

Link to this section Summary

Functions

close_window(arg, inev)

frame(pid)

Fetch the underlying :wxFrame instance object. This represents the window which the webview is drawn into.

iconize(pid, iconize \\ true)

Iconize or restore the window

prepare_url(url)

quit()

Quit the application. This forces a quick termination which can be helpfull on MacOS/Windows as sometimes the destruction is crashing.

rebuild_webview(pid)

Rebuild the webview. This function is a troubleshooting function at this time. On Windows it's sometimes neccesary to rebuild the WebView2 frame.

set_title(pid, title)

Set the windows title

show(pid, url \\ nil)

Show the Window if not visible with the given url.

show_notification(pid, text, opts \\ [])

Show a desktop notification

webview(pid)

Fetch the underlying :wxWebView instance object. Call this if you have to use more advanced :wxWebView functions directly on the object.

Link to this section Functions

close_window(arg, inev)

frame(pid)

Fetch the underlying :wxFrame instance object. This represents the window which the webview is drawn into.

pid - The pid or atom of the Window

Examples

iex> :wx.set_env(Desktop.Env.wx_env())
iex> :wxWindow.show(Desktop.Window.frame(pid), show: false)
false

iconize(pid, iconize \\ true)

Iconize or restore the window

pid - The pid or atom of the Window
restore - Optional defaults to false whether the
```
        window should be restored
```

prepare_url(url)

quit()

Quit the application. This forces a quick termination which can be helpfull on MacOS/Windows as sometimes the destruction is crashing.

rebuild_webview(pid)

Rebuild the webview. This function is a troubleshooting function at this time. On Windows it's sometimes neccesary to rebuild the WebView2 frame.

pid - The pid or atom of the Window

Examples

iex> Desktop.Window.rebuild_webview(pid)
:ok

set_title(pid, title)

Set the windows title

pid - The pid or atom of the Window
title - The new windows title

Examples

iex> Desktop.Window.set_title(pid, "New Window Title")
:ok

show(pid, url \\ nil)

Show the Window if not visible with the given url.

pid - The pid or atom of the Window
url - The endpoint url to show. If non is provided the url callback will be used to get one.

Examples

iex> Desktop.Window.show(pid, "/")
:ok

show_notification(pid, text, opts \\ [])

Show a desktop notification

pid - The pid or atom of the Window
text - The text content to show in the notification
opts - Additional notification options
Valid keys are:
- :id - An id for the notification, this is important if you want control, the visibility of the notification. The default value when none is provided is :default
- :type - One of :info :error :warn these will change how the notification will be displayed. The default is :info
- :title - An alternative title for the notificaion, when none is provided the current window title is used.
- :timeout - A timeout hint specifying how long the notification should be displayed. Possible values are:
  - :auto - This is the default and let's the OS decide
  - :never - Indiciates that notification should not be hidden automatically
  - ms - A time value in milliseconds, how long the notification should be shown
- :callback - A function to be executed when the user clicks on the notification.

Examples

iex> :wx.set_env(Desktop.Env.wx_env())
iex> :wxWebView.isContextMenuEnabled(Desktop.Window.webview(pid))
false

webview(pid)

Fetch the underlying :wxWebView instance object. Call this if you have to use more advanced :wxWebView functions directly on the object.

pid - The pid or atom of the Window

Examples

iex> :wx.set_env(Desktop.Env.wx_env())
iex> :wxWebView.isContextMenuEnabled(Desktop.Window.webview(pid))
false