How to get the best of declarative and imperative paradigms

[rcoreilly]

The Declarative Paradigm

Many standard GUI frameworks use the declarative paradigm, where you construct a new composite object that represents the desired state of a widget, and the framework figures out from that what needs to be updated relative to the current state (i.e., basically performing a diff and applying the resulting patch to the current state). This is done every single time the state changes!

The primary advantage of this paradigm is that the user doesn't need to worry about all the possible ways something might change : you can just create the desired state.

The primary disadvantage is that it ends up putting large chunks of GUI logic into single huge monolithic functions that are deeply nested and complex, with potentially significant amounts of embedded logic. In Go terms, it is basically writing your entire GUI logic within a struct literal expression, which are arguably the most unpleasant and unwieldy expressions in the language.

These declarative constructor expressions need to be massively nested because otherwise you would have to deal with complex logic of finding a particular place to insert a new element, and dealing with the state updating logic that you're trying to avoid in the first place. This means that you cannot use standard programming logic like if and for to flexibly build your GUI elements.

For example, here is an example from the main Flutter sample app:

Widget build(BuildContext context) {
    final screenHeight = MediaQuery.of(context).size.height;
    final trailingActionsBody = Container(
      constraints: const BoxConstraints.tightFor(width: 250),
      padding: const EdgeInsets.symmetric(horizontal: 30),
      child: Column(
        mainAxisAlignment: MainAxisAlignment.end,
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Row(
            children: [
              const Text('Brightness'),
              Expanded(child: Container()),
              Switch(
                  value: useLightMode,
                  onChanged: (value) {
                    handleBrightnessChange(value);
                  })
            ],
          ),
          Row(
            children: [
              useMaterial3
                  ? const Text('Material 3')
                  : const Text('Material 2'),
              Expanded(child: Container()),
              Switch(
                  value: useMaterial3,
                  onChanged: (_) {
                    handleMaterialVersionChange();
                  })
            ],
          ),
          const Divider(),
          _ExpandedColorSeedAction(
            handleColorSelect: handleColorSelect,
            colorSelected: colorSelected,
            colorSelectionMethod: colorSelectionMethod,
          ),
          const Divider(),
          _ExpandedImageColorAction(
            handleImageSelect: handleImageSelect,
            imageSelected: imageSelected,
            colorSelectionMethod: colorSelectionMethod,
          ),
        ],
      ),
    );
    return screenHeight > 740
        ? trailingActionsBody
        : SingleChildScrollView(child: trailingActionsBody);
  }

The code ends up being full of inline ternary logic expressions and other ways of replacing the standard procedural / imperative programming control flow constructs. The excessive boilerplate elements of the Dart language are not doing this code any favors, but even within Go, the equivalent declarative constructors end up being similarly horrible, here in the case of go-app:

func (r *radio) Render() app.UI {
	return app.Main().
		Class("radio").
		Class("fill").
		Body(
			newYouTubePlayer().
				Class("radio-player").
				Class("fill").
				Radio(r.current).
				OnPlaybackChange(r.onPlaybackChange),
			ui.Shell().
				Class("radio-shell").
				Class("fill").
				PaneWidth(menuWidth).
				Menu(newNav().
					LiveRadios(r.lives).
					CurrentRadio(r.current)).
				HamburgerMenu(newNav().
					Class("background-overlay").
					LiveRadios(r.lives).
					CurrentRadio(r.current)).
				Content(
					app.Aside().
						Class("radio-update").
						Class("app-title").
						Class("hspace-out").
						Body(
							ui.Stack().
								Class("fill").
								Right().
								Middle().
								Content(
									app.If(r.isUpdateAvailable,
										newLink().
											Class("link-update").
											Class("glow").
											Label("Update").
											Icon(newSVGIcon().RawSVG(downloadSVG)).
											OnClick(r.onUpdateClick),
									),
								),
						),
					app.Div().
						Class("hspace-out").
						Class("vspace-content").
						Body(
							newInfo().
								Radio(r.current).
								Playing(r.isPlaying),
						),
				),
		)
}

Note the use of app.If to implement conditional logic, and there are similar app.Range constructs.

Fyne uses an imperative mode of updating, but ends up making large nested structures like the declarative paradigm for the initial configuration, as in this example from their tutorial, where the container.NewVBox function takes a list of widgets to add:

	return container.NewVScroll(container.NewVBox(
		widget.NewButton("Info", func() {
			dialog.ShowInformation("Information", "You should know this thing...", win)
		}),
		widget.NewButton("Error", func() {
			err := errors.New("a dummy error message")
			dialog.ShowError(err, win)
		}),
		widget.NewButton("Confirm", func() {
			cnf := dialog.NewConfirm("Confirmation", "Are you enjoying this demo?", confirmCallback, win)
			cnf.SetDismissText("Nah")
			cnf.SetConfirmText("Oh Yes!")
			cnf.Show()
		}),
		openFile,
		saveFile,
		openFolder,
		widget.NewButton("Color Picker", func() {
			picker := dialog.NewColorPicker("Pick a Color", "What is your favorite color?", func(c color.Color) {
				colorPicked(c, win)
			}, win)
			picker.Show()
		}),
		widget.NewButton("Advanced Color Picker", func() {
			advancedPicker.Show()
		}),
		widget.NewButton("Form Dialog (Login Form)", func() {
			username := widget.NewEntry()
			username.Validator = validation.NewRegexp(`^[A-Za-z0-9_-]+$`, "username can only contain letters, numbers, '_', and '-'")
			password := widget.NewPasswordEntry()
			password.Validator = validation.NewRegexp(`^[A-Za-z0-9_-]+$`, "password can only contain letters, numbers, '_', and '-'")
			remember := false
			items := []*widget.FormItem{
				widget.NewFormItem("Username", username),
				widget.NewFormItem("Password", password),
				widget.NewFormItem("Remember me", widget.NewCheck("", func(checked bool) {
					remember = checked
				})),
			}

			dialog.ShowForm("Login...", "Log In", "Cancel", items, func(b bool) {
				if !b {
					return
				}
				var rememberText string
				if remember {
					rememberText = "and remember this login"
				}

				log.Println("Please Authenticate", username.Text, password.Text, rememberText)
			}, win)
		}),
	))

Clearly, there is room for improvement here. There are ways of breaking these functions into smaller components, but the basic issues remain.

Another critical issue with the declarative paradigm is that the final resulting state can end up being a random mashup of old and new, updated elements, which can create problems with coordinating across the different parts of the overall state. This typically requires additional complexity and logic to distinguish between the "state" that might be overwritten by updates.

The Imperative Paradigm

In the imperative paradigm, one calls functions to directly construct the GUI structure, so that standard control flow logic can be used. For example, here's a sample from the Cogent Core demo:

func text(ts *core.Tabs) {
	tab := ts.NewTab("Text")

	core.NewText(tab).SetType(core.TextHeadlineLarge).SetText("Text")
	core.NewText(tab).SetText("Cogent Core provides fully customizable text elements that can be styled in any way you want. Also, there are pre-configured style types for text that allow you to easily create common text types.")

	for _, typ := range core.TextTypesValues() {
		s := strcase.ToSentence(typ.String())
		core.NewText(tab).SetType(typ).SetText(s)
	}
}

The NewX constructor functions take a parent Widget and automatically add themselves to the parent's list of children.

This results in simple, logical code, but what happens if you want to update the configuration based on some kind of state change?

Simple updates to state, such as hover or changing text etc can all be managed by changing state of individual widgets, and are straightforward to handle. Typically, widgets handle these updates themselves. But what happens if you want to make changes across different levels of a set of nested widgets? This logic can become a bit complex, in terms of finding and updating the specific widgets in question. And this update logic ends up being physically separated from the original configuration code, so it is harder to keep the two synchronized.

Furthermore if you want to change the overall structure of a set of nested widgets, it can become even more complicated. Often you end up just resetting everything and rebuilding from scratch, which is obviously less efficient than a declarative mode "diff" update.

The Best of Both Worlds

To get the best of both worlds, we need the following:

• Ability to use standard programming logic, and avoidance of massive nested constructors.
• Co-location of configuration and updating logic.
• Diff-like efficient updating of structure.
• Easy extensibility so end-users and composite elements can selectively override default configuration and updating logic.

[rcoreilly]

Proposal: Hierarchical Config

This is a proposal to achieve the best of both worlds, based on the following elements.

Diff-based update logic

The base/update package provides the diff-like updating logic in a generic form, making minimal "edits" to a slice needed to make it align with a target specification. A key simplification is that the target "template" for what should be there is specified entirely in terms of a string name (which can be any kind of unique id, e.g., a hash code). Existing items in the slice are efficiently moved into the right positions, no-longer-needed elements are deleted, and if any new items are needed, a New function is called with the target name and index to make it.

Widget Config template

Every Widget will have a Config that provides a declarative-like template for its structure and the updating of its components, that then drives the update diff logic.

A key feature of this proposal is that we use a path-based string id instead of literally constructing all the widgets -- this keeps the structure flat and flexible.

This config must be regenerated every time a relevant state update takes place. Unlike in the full declarative case, the template is very lightweight and it is not at all a performance issue to construct it repeatedly.

Timing logic:

• OnInit function sets the individual style and event handlers only for the widget itself.
• Config function creates the widgets own default config and applies it. This happens every Update.
• If we want to be able to override this default config, then we need an additional map of overrides with a stack of functions, which are applied after the native default config.

// ConfigItem represents a Widget configuration element,
// with one New function to create and configure a new child Widget,
// and an Update function to update the state of that child Widget.
// Contains a list of Config for its children, which is all sorted
// out as items are added.
type ConfigItem struct {
	// Path is the / delimited path to the element
	Path string

	// New returns a new Widget of the correct type for this element,
	// fully configured and ready for use.
	New func() Widget

	// Update updates the widget based on current state, so that it
	// propertly renders the correct information.
	Update func(w Widget)

	// Config for Children elements.
	Children Config
}

// Config is an ordered list of [ConfigItem]s,
// ordered in progressive hierarchical order
// so that parents are listed before any children.
// The Key of the map is the path of the element.
type Config []*ConfigItem

// Add adds given config.  This should be called on the root level Config
// list.  Any items with nested paths are added to Children lists as
// appropriate.
func (c *Config) Add(path string, nw func() Widget, updt func(w Widget)) {
...
}

The resulting Config code for a Button looks like this, which is basically a repackaging of the current OnWidgetAdded and Config logic. One clear benefit is putting everything in the same place.

func (bt *Button) Config() {
	var config Config
	// we check if the icons are unset, not if they are nil, so
	// that people can manually set it to [icons.None]
	if bt.HasMenu() {
		if bt.Type == ButtonMenu {
			if bt.Indicator == "" {
				bt.Indicator = icons.KeyboardArrowRight
			}
		} else if bt.Text != "" {
			if bt.Indicator == "" {
				bt.Indicator = icons.KeyboardArrowDown
			}
		} else {
			if bt.Icon == "" {
				bt.Icon = icons.Menu
			}
		}
	}

	config.Add("parts", func() Widget {
		w := NewParts()
		w.Style(func(s *styles.Style) {
			s.Gap.Zero()
			s.Align.Content = styles.Center
			s.Align.Items = styles.Center
		})
		return w
	}, nil)

	if bt.Icon.IsSet() {
		config.Add("parts/icon", func() Widget { return NewIcon() },
			func(w Widget) { w.(*Icon).SetIcon(bt.Icon).Update() })
		if bt.Text != "" {
			config.Add("parts/space", func() Widget { return NewSpace() }, nil)
		}
	}
	if bt.Text != "" {
		config.Add("parts/text", func() Widget {
			w := NewText()
			if bt.Type == ButtonMenu {
				w.Type = TextBodyMedium
			} else {
				w.Type = TextLabelLarge
			}
			w.Style(func(s *styles.Style) {
				s.SetNonSelectable()
				s.SetTextWrap(false)
				s.FillMargin = false
			})
			return w
		}, func(w Widget) {
			w.(*Text).SetText(bt.Text).Update()
		})
	}
	...
	config.ConfigWidget(bt, "")
}

[rcoreilly]

Improved semantic terminology

The process of constructing the overall GUI is composed of two processes, analogous to how almost every other complex entity is made.

1. First you Make the overall Plan that specifies how everything should be built, in a simple, direct, imperative manner, using function closures that directly style and configure a Widget element. Each element is Added to the Plan, either with automatic default naming or AddAt a particular named path in the overall tree.

2. Then you Build the actual Widgets based on the Plan. Critically, the Plan can be updated and modified dynamically as things change, and through the magic of software and the diff-based updating process, the resulting Build can dynamically change as well.

Keeping these two processes logically separate in your mind is key for understanding what goes where, including the critical point that the Plan can be continuously updated, but the actual built elements remain in place unless the plans for that element change.

Customization can happen at both stages of the process: the Plan can be updated by additional Makers that layer on top of the core default Make Plan process, and the Build function can be customized to perform additional steps prior to or after the BuildFromPlan function does the diff-based updating based on the plan. The default BuildWidget wrapper method orchestrates these steps, calling Make to make the Plan, then calling Build, which just calls BuildFromPlan in its default WidgetBase version, but which can be modified to perform additional steps.

[rcoreilly]

• MakeFuncs is a stack of Make(p *Plan) functions that can be associated with any widget, especially frequently used for the overall AppBar Toolbar
• BuildFuncs is a stack of Build(p *Plan ) functions that can also be layered on top of the default Build function, run after that function executes, to manage any post-build custom steps that might require coordination across different widgets -- these should be rare, and most of the building process should be specified locally within the Plan.

[rcoreilly]

In most cases, it is best to design in terms of components that you Plan and Build separately, rather than having everything be part of one giant Plan that encompasses everything in the app. This allows flexibility in later redesigns, and simpler, more encapsulated elements that are then more robust and not so strongly interdependent on each other.

Any necessary interdependency can hopefully be captured by layering MakeFuncs on relevant subcomponent widgets, to update their plans as needed.

[kkoreilly]

Proposal: structurally nested widget planning

The key limitation of the existing proposal is that you can not make automatically named children, since you have to specify the nesting using paths, which are not possible with automatic naming. My proposal addresses this by using a similar system to the existing tree nesting paradigm we use.

In my proposal, you can write this:

splits := core.Add(p, func(w *core.Splits) {})
core.Add(splits, func(w *core.Frame) {})

Instead of:

core.AddAt(p, "splits", func(w *core.Splits) {})
core.AddAt(p, "splits/nav", func(w *core.Frame) {})

In my proposed code above, splits is a variable of type *core.PlanItem, and core.Add just nests appropriately in that, which should even already work without any additional code. I would even propose that we should stop supporting the slash based separation and use the much more robust and programmatic variable approach instead, which would also allow us to get rid of a lot of path handling code in config.

[rcoreilly]

Another option from Kai:

core.Add(p, func(w *core.Splits) {
    w.AddMaker(func(p *core.Plan) {
        core.Add(p, func(w *core.Frame) {})
    })
})

[kkoreilly]

This is actually two tabs per level of nesting, which is quite extreme:

core.Add(p, func(w *core.Frame) { // 1
	w.AddMaker(func(p *core.Plan) {
		core.Add(p, func(w *core.Frame) { // 2
			w.AddMaker(func(p *core.Plan) {
				core.Add(p, func(w *core.Frame) { // 3

				})
			})
		})
	})
})

[kkoreilly]

See fc9ff65 for an example of the effects of this.

[kkoreilly]

App-level declarative paradigm?

Here are two possible ways to write the basic example, both seven lines of code:

Existing way:

package main

import "cogentcore.org/core/core"

func main() {
	b := core.NewBody("Hello")
	core.NewButton(b).SetText("Hello, World!")
	b.RunMainWindow()
}

Potential new declarative way:

package main

import "cogentcore.org/core/core"

func main() { core.Run(NewApp()) }

type App struct { core.Frame }

func (a *App) Make(p *core.Plan) {
	core.Add(p, func(w *Button) { w.SetText("Hello, World!") })
}

[rcoreilly]

Making plans and building widgets, with dynamic updating

(Note: This is provisional documentation for the current state of the new Plan / Build architecture.)

Perhaps the most important challenge for an advanced GUI framework is providing an efficient, logical, and flexible way to construct and dynamically update the GUI contents. One popular "brute force" technique, the declarative approach, is to use exactly the same code for construction and updating, rebuilding the current state every time, and letting the framework figure out what has changed (using a diff-based algorithm).

This is not very computationally or memory efficient, to say the least: our benchmark tests showed factors in the 100x to 1000x range of both computation and memory cost relative to our more optimized approach. It also typically makes it difficult or impossible to use standard programming logic during construction, because everything ends up being written in the form of a giant static literal expression. Furthermore, it introduces significant complexity regarding the status of the active state of the widgets when they are updated.

Our "Plan & Build" alternative approach improves upon the standard declarative approach by using unique name identifiers as keys (like unique map keys) for determining the elements of a Plan for the GUI structure, and putting all the construction code inside a closure that is only executed when a new widget element is actually needed. Thus, all the logic is expressed using standard programming constructs (if, for etc) and new elements are only built when needed. Furthermore, the use of unique name id's allows the diff-like logic to efficiently move items around for insertions and deletions, instead of triggering waves of deletions and construction of new items.

A key general principle behind the core design is to use stacks of closure functions to drive all the subsequent dynamic behavior and updating of the Widget over its subsequent lifetime. Thus, it is important that all of this configuration happens only once when the Widget is first created, so there is one consistent stack of such closures: the Plan and Build structure is designed around this, with initialization functions that are run once when the widget is created, along with the ability to add additional closures that are run at the different levels of updating. Once you have this picture of how things are configured, all of the logic should make good sense.

Build, Rebuild, Restyle

At the broadest level, there are three main phases of construction and updating:

• Initial construction of the GUI for first presentation, which calls Build in the process of making the Scene ready to display. This will trigger OnInit and OnAdd functions for each Widget, which are called when they are first created and added to their parent in the overall GUI tree structure (respectively).

• Rebuild: calls Build on an already-constructed GUI, when something structural might have changed (e.g., a Widget added or removed). Because of the efficient Plan-based logic used for Build, this is very efficient in general. It will trigger a Layout of the entire rendered Scene, which does add an additional time cost, but ensures that any structural changes are properly reflected in the layout of all the widgets.

• Restyle: is an even more efficient update specifically for State changes such as hovering or pressing a Button, enabling or disabling elements, etc. This only triggers a Render of the widget in question, and skips the full layout, and does not make any structural changes. The styling parameters are all designed so that standard state updates specifically do not require a new layout (e.g., the margin automatically accommodates all the possible border and shadow effects that might be triggered by different state-driven style updates). This makes the overall GUI highly responsive and efficient even on slower platforms, for most standard user event-driven updates. The end-user programmer typically does not need to manage this level of updating, as it is automatically handled by the standard Widgets.

Make a Plan, Build Widgets

First, the overall specification of how to make a widget is typically contained within its OnInit method, which is only called once when the widget is first created (prior to when it is added into the GUI tree). Critically, this code is largely in the form of closure functions that will be called later, e.g., during a Build call that happens initially when the Scene is first shown to the user.

A typical OnInit has 3 major sets of functions:

• Styler calls for the widget itself, that set initial and updated styling, which are called during Restyle to update the widget rendering based on state changes.

• Event handling functions such as OnClick that determine what happens in response to user input or other events.

• AddChild functions that add Make functions for adding Widget elements to a Plan, thereby determining the structure of the widget when Build or Rebuild is called.

You can also optionally use Builder to add misc additional updating functions that are called during Build, outside of the Plan logic.

We will use a simple example of a widget with a Text label to illustrate:

type MyWidget struct {
    core.Frame
    Text string
}

func (mw *MyWidget) OnInit() {
    mw.Frame.OnInit()
    // first, do any custom styling _of the widget itself_
    mw.Styler(func(s *styles.Style) {
        s.SetAbilities(true, abilities.Activatable)
        s.Border.Radius = styles.BorderRadiusFull
    })
    // then handle events
    mw.OnClick(func(e events.Event) {
        e.SetHandled()
        fmt.Println("clicked")
    })
    // Make a Plan for GUI structure
    core.AddChild(mw, func(w *core.Text) { // will be called with the newly made Text Widget
        w.Styler(func(s *styles.Style) { // optional extra styling for this widget
            s.Color = colors.C(colors.Red)
        })
        w.Builder(func() {         // will be called whenever Text widget is built
            w.SetText(mw.Text)  // this captures our state to update Text widget
        })
    })
}

As a result of this code, updating the text label can be triggered by:

mw.SetText("new text").Rebuild()

The core.AddChild function combines these two steps:

    mw.Maker(func(p *core.Plan) {
        core.Add(p, func(w *core.Text) {

Thus, it is adding a new Maker function to our Widget that will be called at Build time, and adding a Plan element to that function that will create a new widget of the given type (core.Text). Because Go does not allow methods with their own separate generic types, we have to use global functions like core.AddChild to take advantage of the generic typing based on the call signature of the Add functions.

The plain core.AddChild function automatically generates a unique label for the Plan element based on the code filename, line number, and package, which should be sufficiently unique. There is a core.AddChildAt version that takes an explicit name, which is useful if you need to later find that element by a path name, or you are creating elements in a for loop and thus need to give them unique names based on the loop counter.

After the initial Build call runs the code in our AddChild closure, that code will not be called again, because we don't have any conditional logic so the built structure will always match the Plan. Note that the Styler closure will be called during Restyle. However, the Builder closure is always run at every Rebuild, so the SetText call on the Text element defined there will be called (and Rebuild also rebuilds all of the widgets under the level at which it is called, including that Text element). Note that all the Styler functions are also called during a Rebuild, along with Layout.

You should think of the Text widget as having children within it that represent the text elements that are rendered, so it needs to be rebuilt to update those children. This is handled efficiently using a render.Text text layout instead of separate widgets, but this text layout is still a persistent layout of a given text string, which also drives the sizing of the Text element so it allocates enough room to render the text.

For plans that go beyond the immediate child widgets, you can continue to call core.AddChild function for for that child widget that can add or modify the children of that widget, and so on. For more deeply nested trees, it is a good idea to create makeX(p *core.Plan) methods that can be passed to Maker to handle the making of that sub-element.