diff --git a/gui-easy/gui/easy/scribblings/escape-hatches.scrbl b/gui-easy/gui/easy/scribblings/escape-hatches.scrbl index 255955d..f42141d 100644 --- a/gui-easy/gui/easy/scribblings/escape-hatches.scrbl +++ b/gui-easy/gui/easy/scribblings/escape-hatches.scrbl @@ -6,6 +6,11 @@ racket/gui/easy racket/gui/easy/operator)) +; Example links cited within this section +@(define example-link-close-window + (link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/close-window.rkt" + @filepath{examples/close-window.rkt})) + @title{Escape Hatches} Some views take a @racket[#:mixin] argument that can be used to alter @@ -14,5 +19,5 @@ as ``escape hatches'' when the library doesn't provide a piece of functionality you need, but that functionality is available on the native widget. -See "examples/close-window.rkt" for a example of using a mixin to +See @|example-link-close-window| for an example of using a mixin to programmatically toggle a window's visibility. diff --git a/gui-easy/gui/easy/scribblings/gui-easy.scrbl b/gui-easy/gui/easy/scribblings/gui-easy.scrbl index 575df1e..aaac3b5 100644 --- a/gui-easy/gui/easy/scribblings/gui-easy.scrbl +++ b/gui-easy/gui/easy/scribblings/gui-easy.scrbl @@ -11,8 +11,8 @@ @title{@tt{gui-easy}: Declarative GUIs} @author[(author+email "Bogdan Popa" "bogdan@defn.io")] -This library provides a declarative API on top of -@racketmodname[racket/gui]. +The goal of GUI Easy is to simplify user interface construction in Racket +by wrapping the existing imperative API (@racketmodname[racket/gui]) in a functional shell. @(define-runtime-path youtubestub.tex "youtubestub.tex") @(define embed-style diff --git a/gui-easy/gui/easy/scribblings/quickstart.scrbl b/gui-easy/gui/easy/scribblings/quickstart.scrbl index 7fb72b5..f63cff7 100644 --- a/gui-easy/gui/easy/scribblings/quickstart.scrbl +++ b/gui-easy/gui/easy/scribblings/quickstart.scrbl @@ -9,6 +9,16 @@ @title{Quickstart} +gui-easy can be broadly split up into two parts: observables and views. + +Observables contain values and notify subscribed observers of changes to +their contents. Views are representations of Racket GUI widget trees +that, when rendered, produce concrete instances of those trees and handle +the details of wiring state and widgets together. + +The core abstractions of observables and views correspond to a model-view-controller +(MVC) architecture for graphical applications as popularized by Smalltalk-80. + @section{Hello, World!} @centered[@image[(build-path media "1.1-hello-world.png") #:scale 0.5]] @@ -151,8 +161,23 @@ individual counter by passing in a derived observable to its @racket[make-view] argument. @section{More} - -@(define repo-link - (link "https://github.com/Bogdanp/racket-gui-easy" "Git repository")) - -For more examples, see the "examples" directory in the @|repo-link|. + +For more information about the core concepts of gui-easy and its design, +see @cite["knoblepopa23"]. For more examples, see the "examples" +directory in the @cite["repo-link"]. + + +@(bibliography + @(bib-entry #:key "knoblepopa23" + #:title "Functional Shell and Reusable Components for Easy GUIs" + #:author "D. B. Knoble and B. Popa" + #:location "FUNARCH 2023: Proceedings of the 1st ACM SIGPLAN International Workshop on +Functional Software Architecture" + #:date "31 August 2023 " + #:url "https://arxiv.org/abs/2308.16024") + @(bib-entry #:key "repo-link" + #:title "Declarative GUIs in Racket" + #:author "B. Popa" + #:location "Online" + #:date "Accessed: 28 July 2025" + #:url "https://github.com/Bogdanp/racket-gui-easy")) \ No newline at end of file diff --git a/gui-easy/gui/easy/scribblings/reference.scrbl b/gui-easy/gui/easy/scribblings/reference.scrbl index 6424788..fc6c058 100644 --- a/gui-easy/gui/easy/scribblings/reference.scrbl +++ b/gui-easy/gui/easy/scribblings/reference.scrbl @@ -11,6 +11,17 @@ racket/gui/easy/operator (prefix-in gui: racket/gui))) +; Example links cited within this section +@(define example-link-tabs + (link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/tabs.rkt" + @filepath{examples/tabs.rkt})) +@(define example-link-list + (link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/list.rkt" + @filepath{examples/list.rkt})) + + + + @title{Reference} @defmodule[racket/gui/easy] @@ -64,6 +75,19 @@ @section{Views} +@deftech{View}s are functions that return a @racket[view<%>] instance. + +Views might wrap a specific GUI widget, like a text message or button, or +they might construct a tree of smaller views, forming a larger component. + +Views are typically @tech{Observable}-aware in ways that make sense for each individual view. +For instance the text view takes as input an observable string and the rendered text label updates +with changes to that observable. + +Many @racketmodname[racket/gui] widgets are already wrapped by GUI Easy, but programmers can +implement the @racket[view<%>] interface themselves in order to integrate arbitrary widgets, such as +those from 3rd-party packages in the Racket ecosystem, into their projects. + @subsection[#:tag "windows&dialogs"]{Windows & Dialogs} @defproc[(window [#:title title (maybe-obs/c string?) "Untitled"] @@ -285,7 +309,7 @@ selection changes to an adjacent tab). When tabs are reordered, the choices provided to the action represent the new tab order. - See @filepath{examples/tabs.rkt} for an example. + See @|example-link-tabs| for an example. @history[ #:changed "0.3" @elem{Added the @racket[#:choice=?] argument.} @@ -354,7 +378,7 @@ procedure must return a unique value for each entry in the list, as compared using @racket[equal?]. - See @filepath{examples/list.rkt} for an example. + See @|example-link-list| for an example. } @defproc[(observable-view [data (obs/c any/c)] @@ -818,7 +842,7 @@ @section{Observables} -@deftech{Observables} are containers for values that may change over +@deftech{Observable}s are containers for values that may change over time. Their changes may be observed by arbitrary functions. @; Require the private module to avoid requiring racket/gui/base.