Skip to content

Contributing new widgets

Jump to bottom
sebescudie edited this page Jul 3, 2020 · 2 revisions

This page will give you some guidelines on how to contribute new widgets to the library.

Getting started

Start by cloning the repo to your packages repositories folder, and don't forget to build the solution before opening patches.

How do I build the solution ?

  • Install Visual Studio Community 2019
  • Open Elementa.sln with it (located in 📂src)
  • If the build is configured to Debug, change it to Release (see screenshot)
  • Press CTRL+SHIFT+B
  • Wait for the build to finish and you're done. You should see those lines in the bottom console :
1>Done building project "Elementa.csproj".
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Check how it's done

First, start peeking inside one of the already existing widgets (say, the Slider) to get an understanding of how it works under the hood. The patches lack comments for now, but we're planning to add some so people could understand the innards of the lib by exploring it.

Folder structure

  • Each widget is patched in its own VL document, located in the 📂 vl/Widget folder.
  • Your widget's document must have a dependency to VL.Elementa.Core.
  • Next, you must add a dependency to your widget in the VL.Elementa.Widgets document, and make sur you forward it.

By doing this, you will allow the main document (VL.Elementa) to "see" your widget and in turn to forward it to patches referring VL.Elementa. Indeed, VL.Elementa already has a depedency to VL.Elementa.Widgets.

Documentation

In order for others to see and understand how your widget works, please read on.

Pins and node descriptions

VL allows to add short descriptions (summaries) to nodes and pins, allowing the end user to have some easy to access hints on how your widget is meant to be used. For pins that are common between all widgets, we came up with the following summaries. In case your widget has some specific pins (see for instance the PathDialog widget), please come up with your own.

Input Pins

Pin name Description
Position Sets the widget's position.
Size Sets the widget's size.
Anchor Sets the widget's anchor.
Orientation Sets the widget's orientation.
Go To Focus Forces focus on the widget.
Dragging Behaviour Defines how the widget reacts to mouse input.
Enable Interaction Enables user interaction on the widget. False makes it read-only.
Value Sets the widget's value. Applies on change.
Set Value Applies the value of the Value input to the widget.
Default Sets the widget's defaut value that will be recalled on middle-click.
Minimum Value Sets the widget's minimum value.
Maximum Value Sets the widget's maximum value.
Push Input Value To Observable If true, the On Interaction output will fire when the widget's value is changed from upstream.

Output Pins

Pin Name Description
Output The Elementum
On Interaction Returns the widget's value as an Observable
Value Returns the widget's value

Help Patch

Each widget has its own little help patch, showing it in action in the most simple way possible. This patch also shows the widgets with all optional pins enabled for reference.

  • Those help patches must reside in the 📂help/Topics/Widgets
  • Start by looking at how help patches are made (for instance, look at HowTo Use a Slider.vl and create your own following the same model
  • Don't forget to set a help flag on your widget so the help patch can be retrieved when pressing F1 on your node
  • Also, don't hesitate to do some further reading on how to provide help with VL.

The Widget in Actions patch

Elementa provides a help patch where all widgets are in use, allowing newcomers to quickly get a glimpse of what the library has to offer. This patch is called Reference Widgets in action.vl, and is located in 📂help/Overview.

Please edit this patch by adding your own widget in it!

Clone this wiki locally