{"id":26844897,"url":"https://github.com/patitotective/imtemplate","last_synced_at":"2025-10-16T01:45:39.199Z","repository":{"id":39875401,"uuid":"475250201","full_name":"Patitotective/ImTemplate","owner":"Patitotective","description":"Template for making a single-windowed Dear ImGui application in Nim.","archived":false,"fork":false,"pushed_at":"2024-09-07T18:19:05.000Z","size":5147,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T19:36:57.513Z","etag":null,"topics":["dear-imgui","gui","imgui","imtemplate","nim","nim-lang"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Patitotective.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-29T02:22:41.000Z","updated_at":"2024-10-20T05:12:06.000Z","dependencies_parsed_at":"2023-01-19T16:17:08.208Z","dependency_job_id":"897624b9-48c5-4e6d-85ee-15a891079bc8","html_url":"https://github.com/Patitotective/ImTemplate","commit_stats":null,"previous_names":[],"tags_count":7,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Patitotective%2FImTemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Patitotective%2FImTemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Patitotective%2FImTemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Patitotective%2FImTemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Patitotective","download_url":"https://codeload.github.com/Patitotective/ImTemplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251775764,"owners_count":21641878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dear-imgui","gui","imgui","imtemplate","nim","nim-lang"],"created_at":"2025-03-30T19:33:16.515Z","updated_at":"2025-10-16T01:45:34.161Z","avatar_url":"https://github.com/Patitotective.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg title=\"Icon\" width=50 height=50 src=\"https://github.com/Patitotective/ImTemplate/blob/main/assets/icon.png\"\u003e\u003c/img\u003e ImTemplate\nTemplate for making a single-windowed Dear ImGui application in Nim.\n\n![image](https://github.com/Patitotective/ImTemplate/assets/79225325/6acb8632-1505-4cf9-a520-80255a13c499)\n\n(Check [ImDemo](https://github.com/Patitotective/ImDemo) for a **full** example)\n\n## Features\n- Icon font support.\n- About modal.\n- Preferences system.\n- Settings modal.\n- AppImage support (Linux).\n- Updateable AppImage support (with [gh-releases-zsync](https://github.com/AppImage/AppImageSpec/blob/master/draft.md#github-releases)).\n- Simple data resources support (embed files into the binary).\n- GitHub workflow for building and uploading the AppImage and `.exe` as assets.\n- Non-blocking (using [`std/threadpool`](https://nim-lang.org/docs/threadpool.html)) native system dialogs using [`tinydialogs`](https://github.com/Patitotective/tinydialogs).\n\n(To use NimGL in Ubuntu you might need to install some libraries `sudo apt install libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev libgl-dev`)\n\n## Files Structure\n- `README.md`: Project's description.\n- `LICENSE`: Project's license.\n- `main.nim`: Application's logic.\n- `resources.nim`: To bundle data resources (see [Bundling](#bundling)).\n- `config.nims`: Nim compile configuration.\n- `ImExample.nimble`: [Nimble file](https://github.com/nim-lang/nimble#creating-packages).\n- `assets`:\n  - `icon.png`, `icon.svg`: App icons.\n  - `style.kdl`: Style (using [ImStyle](https://github.com/Patitotective/ImStyle)).\n  - `Cousine-Regular.ttf`, `Karla-Regular.ttf`, `Roboto-Regular.ttf`, `ProggyVector Regular.ttf`: Multiple fonts so you can choose the one you like the most.\n  - `forkawesome-webfont.ttf`: ForkAwesome icon font (see https://forkaweso.me/).\n- `src`:\n  - `types.nim`: Type definitions used by other modules.\n  - `icons.nim`: Helper module with [ForkAwesome](https://forkaweso.me) icons unicode points.\n  - `utils.nim`: Useful procedures, general types or anything used by more than one module.\n  - `settingsmodal.nim`: Draw the settings modal\n\n## Icon Font\nImTemplate uses [ForkAwesome](https://forkaweso.me)'s icon font to be able to display icon in labels, to do it you only need to import [`icons.nim`](https://github.com/Patitotective/ImTemplate/blob/main/src/icons.nim) (where the unicode points for each icon are defined), browse https://forkaweso.me/Fork-Awesome/icons, choose the one you want and, for example, if you want to use [`fa-floppy-o`](https://forkaweso.me/Fork-Awesome/icon/floppy-o/), you will write `FA_FloppyO` in a string:\n```nim\n...\n# main.nim\nimport src/icons\n\nif igButton(\"Open Link \" \u0026 FA_ExternalLink):\n  openURL(\"https://forkaweso.me\")\n```\n\n## App Structure\nThe code is designed to rely on the `App` type (defined in [`utils.nim`](https://github.com/Patitotective/ImTemplate/blob/main/src/utils.nim)), you may want to store anything that your program needs inside it.\n```nim\ntype\n  App* = object\n    win*: GLFWWindow\n    config*: Config\n    prefs*: KdlPrefs[Prefs]\n    fonts*: array[Config.fonts.len, ptr ImFont]\n    resources*: Table[string, string]\n\n    maxLabelWidth*: float32\n    messageBoxResult*: FlowVar[Button]\n    # Add your variables here\n    ...\n```\n- `win`: GLFW window.\n- `fonts`: An array containing the loaded fonts from `Config.fonts`.\n- `prefs`: See [Prefs](#prefs).\n- `config`: Configuration file (loaded from `config.toml`).\n- `resources`: Data resources where the key is the filename and the value is the binary data.\n- `maxLabelWidth`: This is a value that's used to draw the settingsmodal (see https://github.com/Patitotective/ImTemplate/blob/main/src/settingsmodal.nim)\n- `messageBoxResult`: This variable stores the result to a message box dialog opened by [`tinydialogs`](https://github.com/Patitotective/tinydialogs), it uses the `FlowVar` type since it's the result of a spawned thread.\n\n## Config\nThe configuration stores data like name and version of the application, it is stored in its type definition in `src/configtype.nim` using `constructor/defaults` to define the default values:\n```nim\ntype\n  Config* = object\n    name* = \"ImExample\"\n    comment* = \"ImExample is a simple Dear ImGui application example\"\n    version* = \"2.0.0\"\n    website* = \"https://github.com/Patitotective/ImTemplate\"\n    authors* = [\n      (name: \"Patitotective\", url: \"https://github.com/Patitotective\"),\n      (\"Cristobal\", \"mailto:cristobalriaga@gmail.com\"),\n      (\"Omar Cornut\", \"https://github.com/ocornut\"),\n      (\"Beef, Yard, Rika\", \"\"),\n      (\"and the Nim community :]\", \"\"),\n      (\"Inu147\", \"\"),\n    ]\n    categories* = \"Utility\"\n\n    stylePath* = \"assets/style.kdl\"\n    iconPath* = \"assets/icon.png\"\n    svgIconPath* = \"assets/icon.svg\"\n\n    iconFontPath* = \"assets/forkawesome-webfont.ttf\"\n    fonts* = [\n      font(\"assets/ProggyVector Regular.ttf\", 16f), # Other options are Roboto-Regular.ttf, Cousine-Regular.ttf or Karla-Regular.ttf\n      font(\"assets/NotoSansJP-Regular.otf\", 16f, GlyphRanges.Japanese),\n    ]\n\n    # AppImage\n    ghRepo* = (user: \"Patitotective\", repo: \"ImTemplate\").some\n    appstreamPath* = \"\"\n\n    # Window\n    minSize* = (w: 200i32, h: 200i32) # \u003c 0: don't care\n```\n### Fields Explanation\n- `name`: App's name.\n- `comment`: App's description.\n- `version`: App's version.\n- `website`: A link where you can find more information about the app.\n- `authors`: An array containing information about the authors.\n- `categories`: Sequence of [registered categories](https://specifications.freedesktop.org/menu-spec/latest/apa.html) (for the AppImage).\n- `stylePath`: App's ImStyle path (using https://github.com/Patitotective/ImStyle).\n- `iconPath`: PNG icon path.\n- `svgIconPath`: Scalable icon path\n- `iconFontPath`: [ForkAwesome](https://forkaweso.me)'s font path.\n- `fonts`: An array of `Font` objects containing the font's path, size and range of glyphs for japanese, korean, chinese, etc.\n- `ghRepo`: GitHub repo to fetch releases from (if it's some it will generate an `AppImage.zsync` file, include it in your releases for [AppImage updates](https://docs.appimage.org/packaging-guide/optional/updates.html#using-appimagetool)).\n- `appstreamPath`: Path to the [AppStream metadata](https://docs.appimage.org/packaging-guide/optional/appstream.html).\n- `minSize`: Window's minimum size, use numbers less than zero to disable a limit.\n\n### About Modal\nUsing the information from the config object, ImTemplate creates a simple about modal.\n\n![image](https://github.com/Patitotective/ImTemplate/assets/79225325/9574cd96-0f77-4032-bd0a-34ca49217d21)\n\n## Prefs\nThe preferences is the data that can change during runtime and that data that you want to store for the future like the position and size of the window, this includes the settings the user can change like the language and theme.\nThe preferences are saved in a KDL file (using [kdl/prefs](https://patitotective.github.io/kdl-nim/kdl/prefs.html)).\nYou just have to provide an object including all the data you want to store as fields:\n```nim\ntype\n  Prefs* {.defaults: {defExported}.} = object\n    maximized* = false # Was the window maximized when the app was closed?\n    winpos* = (x: -1i32, y: -1i32) # Window position\n    winsize* = (w: 600i32, h: 650i32) # Window size\n    settings* = initSettings()\n```\n\n### Settings\nThe settings are preferences that the user can modify through the settings modal.\n\n![image](https://github.com/Patitotective/ImTemplate/assets/79225325/0b268d5a-e034-4541-be96-954263bab2ae)\n\nYou can define all the settings' settings (i.e.: combobox, checkbox, input, etc.) through the `Settings` object:\n```nim\ntype\n  Os* {.defaults: {}.} = object\n    file* = fileSetting(display = \"Text File\", filterPatterns = @[\"*.txt\", \"*.nim\", \"*.kdl\", \"*.json\"])\n    files* = filesSetting(display = \"Multiple files\", singleFilterDescription = \"Anything\", default = @[\".bashrc\", \".profile\"])\n    folder* = folderSetting(display = \"Folder\")\n\n  Numbers* {.defaults: {}.} = object\n    spin* = spinSetting(display = \"Int Spinner\", default = 4, range = 0i32..10i32)\n    fspin* = fspinSetting(display = \"Float Spinner\", default = 3.14, range = 0f..10f)\n    slider* = sliderSetting(display = \"Int Slider\", default = 40, range = -100i32..100i32)\n    fslider* = fsliderSetting(display = \"Float Slider\", default = -2.5, range = -10f..10f)\n\n  Colors* {.defaults: {}.} = object\n    rgb* = rgbSetting(default = [1f, 0f, 0.2f])\n    rgba* = rgbaSetting(default = [0.4f, 0.7f, 0f, 0.5f], flags = @[AlphaBar, AlphaPreviewHalf])\n\n  Sizes* = enum\n    None, Huge, Big, Medium, Small, Mini\n\n  Settings* {.defaults: {}.} = object\n    input* = inputSetting(display = \"Input\", default = \"Hello World\")\n    input2* = inputSetting(\n      display = \"Custom Input\", hint = \"Type...\",\n      help = \"Has a hint, 10 characters maximum and only accepts on return\",\n      limits = 0..10, flags = @[ImGuiInputTextFlags.EnterReturnsTrue]\n    )\n    check* = checkSetting(display = \"Checkbox\", default = true)\n    combo* = comboSetting(display = \"Combo box\", items = Sizes.toSeq, default = None)\n    radio* = radioSetting(display = \"Radio button\", items = @[Big, Medium, Small], default = Medium)\n    os* = sectionSetting(display = \"File dialogs\", help = \"Single file, multiple files and folder pickers\", content = initOs())\n    numbers* = sectionSetting(display = \"Spinners and sliders\", content = initNumbers())\n    colors* = sectionSetting(display = \"Color pickers\", content = initColors())\n```\n\n## Building\nTo build your app you may want to run `nimble buildr` task.\nYou can set the following environment variables to change the building process:\n- `ARCH`: the architecture used to compile the binary, by default `amd64`.\n- `OUTPATH`: the path of the binary file (or exe file on Windows), by default \"name-version-arch\"\n- `FLAGS`: any other flags you want to pass to the compiler, optional.\n\n**_Note: Unfortunately on Window most of the times Nim binaries are flagged as virus, see https://github.com/nim-lang/Nim/issues/17820._**\n\n### Bundling\nTo bundle your app resources inside the compiled binary, you only need to go to [`resources.nim`](https://github.com/Patitotective/ImTemplate/blob/main/resources.nim) file and define their paths in the `resourcesPaths` array.\nAfter that `resources` is imported in `main.nim`. So when you compile it, it statically reads those files and creates a table with the binary data.\nTo access them use `app.resources[\"path\"]`.\nBy default this is how `resourcesPaths` looks like:\n```nim\n...\nconst resourcesPaths = @[\n  config.stylePath,\n  config.iconPath,\n  config.iconFontPath,\n] \u0026 config.fonts.mapIt(it.path) # Add the paths of each font\n...\n```\n\n### Nimble\nYou can publish your application as a [binary package](https://github.com/nim-lang/nimble#binary-packages) with nimble.\n\n### AppImage (Linux)\nTo build your app as an AppImage you will need to run `nimble buildapp`, it will install the dependencies, compile the app, check for `appimagetool` (and install it if its not found in the `$PATH`), generate the `AppDir` directory and finally build the AppImage.\nIf you included `ghRepo` in the config, it will also generate an `AppImage.zsync` file. You should attach this file along with the `AppImage` to your GitHub release.\nIf you included `appstreamPath`, it will get copied to `AppDir/usr/share/shareinfo/{config.name}.appdata.xml` (see https://docs.appimage.org/packaging-guide/optional/appstream.html).\n\n### Creating a release\nImTemplate has a [`release.yml` workflow](https://github.com/Patitotective/ImTemplate/blob/main/.github/workflows/release.yml) that automatically when you publish a release, builds an AppImage and an `.exe` file to then upload them as assets to the release.\nThis can take several minutes.\n\n## Generated from ImTemplate\nApps using this template:\n- [ImDemo](https://github.com/Patitotective/ImDemo).\n- [ImPasswordGen](https://github.com/Patitotective/ImPasswordGen).\n- [ImClocks](https://github.com/Patitotective/ImClocks).\n- [ImThemes](https://github.com/Patitotective/ImThemes).\n\n(Contact me if you want your app to be added here).\n\n## About\n- Icon Font: https://forkaweso.me (MIT).\n- GitHub: https://github.com/Patitotective/ImTemplate.\n- Discord: https://discord.gg/U23ZQMsvwc.\n\nContact me:\n- Discord: **Patitotective#0127**.\n- Twitter: [@patitotective](https://twitter.com/patitotective).\n- Email: **cristobalriaga@gmail.com**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatitotective%2Fimtemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatitotective%2Fimtemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatitotective%2Fimtemplate/lists"}