-
-
Notifications
You must be signed in to change notification settings - Fork 5
OS Integration tips
This page lists tips many common tasks when developing applications for different platforms
Resource files in Windows are special scripts that can be used to set different resources for your application, such as icons, cursors, string tables, etc.
The main use for a resource file in your application will mainly be setting the application's icon. They are capable of much more, but most of the time you'd find it easier and more practical to use the framework's facilities, such as the i18n module for localisation.
Here is the most basic example of a resource file:
#include "resource.h"
IDI_APP_ICON ICON "Icon.ico"
This resource file, as well as resource.h
can be found under the Config/Resources/
folder. More information on resources can be found here.
Warning
When editing resource.h
you might encounter an error citing an unexpected end of line. To fix it simply add an empty line at the bottom of the file.
As said in the previous paragraph, icons in resource files are in the .ico
format, which is similar to the Apple .icns
format, by their ability to store images of multiple sizes in a single icon file.
Tip
The image names in Config/Resources/Icon.iconset
are completely compatible with .ico
files, so it's best you put all your icons there and reuse them for macOS and Windows
In order to create a .ico
file, install ImageMagick, which is a utility for converting between different image formats.
Using the following command you can generate a .ico
file in your Config/Resources
directory:
user $ cd Config/Resources/Icon.iconset/
user $ magick *.png Icon.ico && mv Icon.ico ../
Tip
If ImageMagick is detected on your system, the build scripts will automatically try to compile your
Unlike on macOS, or Linux, where such settings are stored in a per-application file, on Windows, you have to write to the registry. Stack overflow question for more information.
It's a good practice to do this step in your application's installer script, so that elevated privileges are required only during installation.
Since macOS is Unix-based, the default installation directories set in the UVKBuildTool are set to the standard Unix directories.
This is fine for utility applications, that you do not want to be discoverable in application menus, however, if your application is made to be used by normal users, you will need to implement an application bundle.
An application bundle is a special type of folder that contains your application's binaries and some additional metadata. These application bundles are installed to the /Applications
folder and have the .app
extension.
These bundles can then be further archived into the familiar .dmg
format, where they can then be distributed to users on your website, an app store, or a package manager, like Homebrew.
In order to enable the creation of application bundles, you need to modify your uvproj.yaml
file to enable bundling.
Here is an example that enables both bundling, and packaging:
name: "UImGuiDemo"
version: "1.0.0.0"
engine-version: "1.0.0.0"
build-mode-static: false
build-mode-vendor: true
system-wide: false
macos:
bundle: true
Caution
Application bundles are self-contained which means that some settings in your uvproj.yaml
file might not behave as expected:
- Compilation is always in vendored mode, because your application can only rely on the OS libraries
- The framework is always going to be installed, for the same reason
Now that you have enabled bundling, you need to set up your Info.plist
file. Since release v0.9.9.8 of the framework each newly created project should have the macOS
folder containing an Info.plist
file. Example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- Application Metadata -->
<key>CFBundleName</key>
<string>UImGuiDemo</string>
<key>CFBundleDisplayName</key>
<string>UntitledImGuiFramework Demo</string>
<key>CFBundleIdentifier</key>
<string>com.madladsquad.UImGuiDemo</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>CFBundleShortVersionString</key>
<string>1.0.0</string>
<!-- Executable -->
<key>CFBundleExecutable</key>
<string>UImGuiDemo</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<!-- Icon -->
<key>CFBundleIconFile</key>
<string>example-icon</string>
<!-- Minimum macOS Version -->
<key>LSMinimumSystemVersion</key>
<string>12.0.0</string>
<!-- High Resolution Support -->
<key>NSHighResolutionCapable</key>
<true/>
<!-- Application Category -->
<key>LSApplicationCategoryType</key>
<string>public.app-category.utilities</string>
<!-- Security Configuration -->
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<false/>
</dict>
</dict>
</plist>
This file is installed automatically when targeting an application bundle.
Tip
The Info.plist
file can also be used to define the types of files your application can open.
Application bundles require icons to be in the .icns
format. In order to generate such a file for your application, you can use iconutil
, which is a standard utility that should already be installed on your system.
To package your icons, do the following:
- Create a folder named
<application name>.iconset
- Add your icon at different sizes, so that your folder's structure looks like this:
AppIcon.iconset/ ├── icon_16x16.png ├── [email protected] ├── icon_32x32.png ├── [email protected] ├── icon_128x128.png ├── [email protected] ├── icon_256x256.png ├── [email protected] ├── icon_512x512.png ├── [email protected]
- After that, run
iconutil -c icns AppIcon.iconset
to generate anAppIcon.icns
file
When building the bundle, the UVKBuildTool will try to create an icon set and install it correctly as App.app/Contents/Resources/App.icns
.
Tip
Sometimes, during local development and testing, you may encounter an issue, where the application displays the correct item in the application drawer when opened, but it doesn't, in other places, such as Finder. This can usually be solved by either restarting Finder using killall Finder
, or by restarting your computer.
This is caused by Finder and other system UI, having updated the applications database, before your build system could fully install everything in /Applications
, leading these application to believe that your application is corrupt in some way.
Creating .dmg
installers for your application is out of the scope of the framework's build system, due to the many options and edge-cases that need to be handled. Check out a project like create-dmg for a nice CLI utility for creating .dmg
installers.
On Unix-based systems, it's really important to make sure you're following the Filesystem hierarchy standard and XDG base directory specifications. You can use the XDG basedir submodule for an easy way to get the correct directories.
When developing an application for freedesktop-based systems, you need a .desktop
file for it. This file lists metadata, that controls the following:
- Whether the application can be seen in the menus
- What file types the application can open
- The icon of the application on some desktop environments(for example, GNOME)
- Right-click items on the dock/taskbar
- Name of the application in multiple languages
- And more
Here is an example desktop file, which details everything about it. After being installed to /usr/share/applications/
the application will appear in the menus and application search in the desktop.
[Desktop Entry]
Type=Application
Version=1.0
Name=UntitledDesktop Session Logout
GenericName=SessionLogout
Comment=Allows the user to log out, power off, restart and put the computer to sleep using a GUI
Icon=ude-session-logout
TryExec=ude-session-logout
Exec=ude-session-logout
Categories=System;Utility;
Terminal=false
StartupNotify=false
StartupWMClass=ude-session-logout
More information on the Freedesktop desktop entry specification.
Tip
Always set the StartupWMClass
property of the desktop file to your application's binary name, as set in the uvproj.yaml file. This makes some desktop environments, like GNOME, to use the correct icon for your application's window.
Many applications may need to interact with the desktop environment as part of their feature set. On Freedesktop systems most interactions between applications go through standardised DBus interfaces. You can enable the dbus submodule to easily communicate over the bus in a type- and memory-safe manner.
There are many standard interfaces, however there are 2 main types:
- Normal interfaces
- XDG desktop portals
Normal interfaces and XDG desktop portal interfaces can be very similar, however there are a few differences. For starters, XDG desktop portals were created for applications that were are containerised in environments like Flatpak or Snaps. They may provide better security features, or may be updated more frequently compared to normal interfaces. On the other hand, they may lack many features that might be a security concern in containerised workflows.
A list of XDG desktop portal interfaces can be found here.
A list of normal standardised DBus interfaces can be found here, though they are mixed with other XDG standards.
This project is supported by all the people who joined our discord server and became beta testers. If you want to join the discord you can click here.
- Home
- Beginner content
- Install guide
- Creating and using the UI components
- The Instance
- The Init Info struct
- Textures
- Logging
- Unicode support
- Additional features
- Client-side bar
- Custom type definitions
- Memory management
- C API development
- Config files and Folders
- Interfaces
- Internal Event safety
- Customising the build system
- Modules system
- Collaborating with others
- Advanced content
- Developer and contributor resources
- Misc