Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
NC* is written in the [[https://odin-lang.org|ODIN]] programming language. Before we begin, it is expected you have some knowledge of low-level programming languages, or ideally a basic understanding of ODIN. This guide will not be teaching programming.

The reasons to choose ODIN are multifaceted, but the primary reason is its simplicity and approachable design, certainly far easier to pick up than C or C++. There will be references to things like ''cstring'' and ''string'', where you will be expected to know how to use them in what circumstances.

As ODIN has no concept of references, we will do our best to explain best practices as the by-value concept may seem strange initially for those used to using references. You very rarely need to dereference a pointer in ODIN, unlike in C/C++ where it's practically everywhere. In fact, as time moves on, it is unlikely NC* will be dereferencing anything.

Other things to note:

  * There are few heap allocations in NC*. What is heap allocated is usually done by ODIN automatically, such as the ''string'' type, or where we make use of the ''make'' or ''new'' procedure using the standard allocator. The primary and global state structure, ''UI_State'' is heap allocated from the ''UI_Init'' procedure, but besides this, everything is stack allocated and moved into the state as required. Where we perform allocations into ''temp_allocator'', we would tell you.
  * In addition to the above, you will find that almost every procedure returning a value is constructed on the stack and expected to be stored in the global state, outside of utility procs. Unless the state is passed in by pointer into the procedure, we make no assumptions on where the final data goes. You are expected to know what you're doing with this data unless directed otherwise in these guides.
  * As ODIN performs everything by value, every local declaration to another data source is copied by default unless you explicitly take a pointer to it. This is a low-level language after all. In the NC* codebase, we favour explicitness over local variables so that it's clear what data is being put where.
  * And finally, touching on the Immediate vs Retained mode argument, NC* draws everything "Immediate"-mode style with an eventual toggle to "Retained" later. At the moment, even though there is a global state for ''Content'', each Component stores a copy. This may change later, but would not work in Retained-mode. Please keep this in mind when reading these guides, as the Immediate vs Retained will naturally prop up. The goal of NC* is not to repeat the mistakes that almost all Retained-mode API's do, which is being opinionated.

Now this is all said and done, let's move on.

====== Concepts ======

There are two different concepts in NC* to understand before we can move onto coding.

  * Compositions are structures that contain Shapes and their respective dimensions within the overall Composition, given a bounding dimension. Each Composition is therefore the thing that NC* uses to draw the thing itself, but does not contain any data or behaviours, this comes later.
  * Components, on the other hand, are the things that contain behaviour, data and properties which can either change or modify one or more Compositions. A ''ComponentDefinition'' is used to describe the default construction of a component, which can have one or more Compositions. A ''Component'' is something that is created and stored into the global UI stack, which takes a reference to a definition to determine what to draw. Component's will "retain" a copy of a Composition that the Component should draw based on its current state.

When creating our own custom components, understanding these two concepts is vital for the construction of these components and how they are drawn.

Below is the expected dependency chain.

  - ''Shape'' -> ''Composition'' -> ''ComponentDefinition'' -> ''Component''

As you can see, there is no data involved. That's because we are storing data globally and accessing it per Component.

When creating definitions, we give an identifier which we use to construct with later. Then, Components are added to the global state from these definitions which are used to create our interface. If they hold content, the ''Content'' type is used for holding our content and is assigned to the global state and accessed via the integer identifier given to us from the global stack. We can use this to move data around easily, instead of trying to use procedures to pass around our data all the time.

In the case of ''Content'', we take advantage of the ''union'' type in ODIN which we use to hold a certain specific number of types we would accept. This is compile-time types which are easy to type-check and less error-prone than using the ''any'' type we could have used. Note that when we use ''Content'', basic types are copied by value as usual, but user-defined types will be pointers to an underlying type. Moreover, when dealing with these pointers, we are expecting the underlying types to be heap allocated, not stack allocated.

The main reason to do this is because ''Content'' as a type in the global stack is a value type, not a pointer, so if data is considered "complex" (i.e., not a basic type), then heap allocate the data and make a reference to it for the ''Content'' to use later. This prevents loss of data or losing data in scopes where we expected a value copy. You can use the ''temp_allocator'' when allocating if a memory arena is preferred over a straight heap allocation, or your own allocator. The reason the ''Content'' type is a union is we can expand this to store values of any type which you, the user, can type-check manually later if desired.

==== Structure ====

Besides the basic structure defined above for building interfaces, everything else is left to the user to define how to structure the Components themselves.

All your member variables, procedures and business logic is done yourself if building components from scratch, and NC* will not care much how that's done, besides one simple caveat:

  * If you let NC* do event management for you, it will give you a state you can use to determine things like if the mouse is interacting with your component; or,
  * If you want to go wild, build your own custom event handling within your component and be warned of the risks. We will put in mechanisms in NC* to enable or disable UI interactions based on your own custom component's activities, but be aware that this freedom comes at a cost. Otherwise, building strictly within the confines of NC*'s event handling is easier despite the inherent overhead and tediousness that comes with it.

We try our best to make your life as simple as possible in this regard.

We can move on to the next chapter once you're ready.