Loading...

Main page: Hello world tutorial

This tutorial makes a simple hello world example app:

Notice how you can see the result of the code above, a button with the text “Hello, World!”. Not only can you see the result of the code, you can edit the code live. Try changing “Hello, World!” to “Click me!” and you will see the button update accordingly.

Main page: App

The first call in every app is core.NewBody. This creates and returns a new core.Body, which is a container in which app content is placed. This takes an optional name, which is used for the title of the app/window/tab.

After calling NewBody, you add widgets to the body that was returned, which is typically given the local variable name b for body.

Then, after adding content to your body, you can create and start a window from it using core.Body.RunMainWindow.

Therefore, the standard structure of an app looks like this:

For most of the code examples on this website, we will omit the outer structure of the app so that you can focus on the app content.

Main page: Widget

All app content is organized into widgets, which are reusable app components that render, store information, and handle events. See widgets for a list of widget types.

All widgets satisfy the core.Widget interface. Widgets are typically created by calling the core.New{WidgetName} function (for example: core.NewButton). All of these New functions take a parent in which the widget is added. This allows you to create nested widget structures and layouts that position and size widgets in different ways. For elements at the root level of your app, the parent is b, the app body. However, if your widget is located in a some other container, you would pass that as the parent.

Many widgets define attributes that you can set, like the text of a button. These attributes can be set using the Set{AttributeName} method (for example: core.Button.SetText). These Set methods always return the original object so that you can chain multiple Set calls together on one line. You can also always access the attributes of a widget by directly accessing its fields.

Here is an example of using New and Set functions to construct and configure a widget:

You can always assign a widget to a variable and then get information from it or make further calls on it at any point. For example:

Main page: Event

An event is a user action that you can process. See events for explanations of common event types.

To handle an event, simply call the On{EventType} method on any widget. For example:

The events.Event object passed to the function can be used for things such as obtaining detailed event information. For example, you can determine the exact position of a click event:

Main page: Style

Styling allows you to easily customize the appearance of widgets at any level. See styles for explanations of common style properties. You can experiment with style properties in the style playground.

You can change any style properties of a widget:

You can change the colors of a widget using Cogent Core’s dynamic color scheme system:

You can change the size of a widget using Cogent Core’s flexible unit system:

Main page: Update

There are several ways to dynamically update the content of an app.

The simplest way to update a widget is to call core.WidgetBase.Update after changing any of its properties:

You can also register a tree.NodeBase.Updater that will get called when the widget is updated. This can allow you to more closely couple widgets with their updating logic:

Main page: Bind

Value binding allows you to link the value of a variable and the value of a widget, ensuring that they automatically stay up-to-date.

For example, the update example can also be written as:

That code uses core.Bind to bind the value of the variable count to the text of the widget text, meaning that the text will be updated from the variable whenever core.WidgetBase.Update is called.

You can use value binding with more than just text widgets; most widgets implement the core.Value interface and thus support value binding. For example, this code uses value binding with a switch and a corresponding bool value:

Note that value binding goes both ways: not only is the value of the widget updated in core.WidgetBase.Update, the value of the bound variable is updated before core.WidgetBase.OnChange. This two-way updating makes value binding very useful for creating interactive widgets that represent some underlying value.

Main page: Plan

The previous two sections cover how to update the properties of a widget, but what if you want to update the structure of a widget? To answer that question, Cogent Core provides plans, a mechanism for specifying what the children of a widget should be, which is then used to automatically update the actual children to reflect that.

For example, this code uses tree.Plan through tree.NodeBase.Maker to dynamically update the number of buttons in a frame:

Plans are a powerful tool that are critical for some widgets such as those that need to dynamically manage hundreds of children in a convenient and performant way. They aren’t always necessary, but you will find them being used a lot in complicated apps, and you will see more examples of them in the rest of this documentation.

Main page: Async

Most of the time, updating happens synchronously through event handlers, stylers, updaters, and makers. However, sometimes you need to update content asynchronously from another goroutine. When you do so, you just need to protect any updates you make to widgets with core.WidgetBase.AsyncLock and core.WidgetBase.AsyncUnlock.

For example, this code utilizes a goroutine to update text to the current time every second: