Documentation for Simple Example

[jakebruemmer]

Hi there,

This library looks great, but I'm wondering if there is documentation in addition to some of the examples that are hosted in the repo. It's a little intimidating for someone that doesn't have any Lib UI experience, so maybe there is some documentation for beginners somewhere? I'm basically trying to make something that looks like the attached image. I can also close this and post it to StackOverflow if that'd be a better place, but I thought it would maybe be appropriate as an issue as there might be other beginners like me looking for this type of documentation.

[AndyObtiva]

This code seems to accomlish your goal from testing on the Mac only at least (App below contains the main view that you shared on the right):

require 'glimmer-dsl-libui'

# This is a LoginRequest model
class LoginRequest
  ALLOWED_USERNAMES = %[john joe bob nancy gomez]

  attr_accessor :username
  attr_reader :result

  def login
    @result = ALLOWED_USERNAMES.include?(username.to_s.downcase)
  end
end

# By declaring this view as a Glimmer::LibUI::CustomWindow, you can later use `login_screen`
# as Glimmer GUI  keyword to instantiate LoginScreen underneath a parent
class LoginScreen
  include Glimmer::LibUI::CustomWindow

  # Accept login_request model as an option that is an instance of LoginRequest
  option :login_request

  body {
    window('Login') {
      margined true

      vertical_box {
        form {
          entry {
            label 'Username:'
            text <=> [login_request, :username]
          }
        }

        button('Login') {
          on_clicked do
            login_request.login
            # the following 2 lines close window and LibUI runtime for that window
            body_root.destroy
            ::LibUI.quit
          end
        }
      }
    }
  }
end

# By declaring this view as a Glimmer::LibUI::CustomWindow, you can later use `copy_screen`
# as Glimmer GUI  keyword to instantiate CopyScreen underneath a parent
class CopyScreen
  include Glimmer::LibUI::CustomWindow

  option :item

  body {
    window('Copy') {
      margined true

      label("Copying #{item} in progress...")
    }
  }
end

# By declaring this view as a Glimmer::LibUI::CustomWindow, you can later use `show_screen`
# as Glimmer GUI  keyword to instantiate ShowScreen underneath a parent
class ShowScreen
  include Glimmer::LibUI::CustomWindow

  option :item

  body {
    window('Copy') {
      margined true

      label("Showing #{item} content...")
    }
  }
end

class App
  include Glimmer::LibUI::Application

  ITEMS = 4.times.map {|n| "Item #{n+1}" }

  before_body do
    # start by instantiating a LoginRequest model
    login_request = LoginRequest.new
    # login_screen builds an instance of LoginScreen while
    # passing it the login_request option.
    # Its show method will block until the window is closed
    login_screen(login_request: login_request).show
    # if login result is false, then exit app completely
    if !login_request.result
      exit(0)
    end
  end

  body {
    window('App') {
      margined true

      vertical_box {
        ITEMS.each do |item|
          horizontal_box {
            label(item)

            button('Copy') {
              on_clicked do
                copy_screen(item: item).show
              end
            }

            button('Show') {
              on_clicked do
                show_screen(item: item).show
              end
            }
          }
        end
      }
    }
  }
end

App.launch

At the bottom of the README Usage section, it says the following for Beginners (I probably should move this elsewhere to make it more prominent [update: done]):

"If you are new to Glimmer DSL for LibUI, check out the Glimmer GUI DSL Concepts, Glimmer Command, Girb and Examples to quickly learn through copy/paste. You may refer to the API later on once you have gotten your feet wet with Glimmer DSL for LibUI and need more detailed reference information."

I think what matters the most are:

• Glimmer GUI DSL Concepts
• Examples

Learn by going through every example (run locally) while searching the README for anything that matches what you see in the examples. You need to graduate gradually in knowledge on how to build desktop applications.

Otherwise, I highly recommend watching the RubyConf 2022 presentation on Building Native GUI Apps in Ruby: https://www.youtube.com/watch?v=1Bh4CnJqHyY&feature=youtu.be

It breaks down the Glimmer DSL for LibUI concepts into small bits. But, you still need to apply the concepts by going through the Examples.

You are also welcome to ask me any questions here in Issues or on the Glimmer Gitter chat. I don't mind answering questions assuming an educated and serious Software Engineer.

In the meantime, if you could think of any improvements to documentation for beginners, please share ideas in Issues or doc submissions in Pull Requests.

[jakebruemmer]

Wow, this is incredibly helpful. I will try and put together a working copy today based off of this and let you know how it goes. Thank you!

[jakebruemmer]

Alright, I got something working locally and pushed an initial version to https://github.com/jakebruemmer/adamantite.

I made a couple of tweaks to the code that you provided, but it's pretty much the same. Thank you for helping me understand the Glimmer UI lib a bit better. The creation and usage of classes makes a lot more sense now.

[AndyObtiva]

This is great news!! I am closing this issue as a result.

If you think of any more questions in the future, you are welcome to ask me in the Glimmer Gitter chat or here if it’s related to the code mentioned above (you can reply even if the issue is closed).

Cheers.