Brief introduction to the Atomic Design Methodology

If you haven’t heard about Atomic Design before, I really recommend that you dig a bit into this topic. With this way of methodology in mind, we will start building the smallest controls we can. Then, we will compose more complex controls reusing the smallest.

Keep in mind you don’t really need to blindly follow the Atoms, Molecules and Organisms proposed categories, and don’t overthink where to categorize them. As long as you can compose controls with other controls, that’s perfect. Adapt it to your own personal way of building software.

The idea resonates perfectly with Xojo and, while we will create a few web controls in this example, you can apply it to other targets like Desktop or Mobile.

Here is a video from Brad Frost, the person behind Atomic Design Methodology.

Containers to the rescue!

In this case, we won’t need to use any Web SDK control, CSS or JavaScript. We will be using just plain Xojo Web Containers for creating our Atoms and Molecules.

This is how Twitter’s navigation sidebar looks like:

We will create something similar. Using Atomic Design, let’s break it down it into a few new reusable controls:

Each Atom, Molecule and Organism will be a Container. In the above image, we have identified each of them.

• There is a “Navigation Link Icon”, an Atom, which will show one of the available Bootstrap Icons. As you notice in the Twitter example, if the link is active, the icon will be filled.
• For the label Atom, we can just use the WebLabel built-in control. There is no need to wrap it in a Container, in this case.
• The navigation link will be a Molecule, combining the icon and the label.
• The Active Link Indicator will move to the active link, using an animation.
• Finally, the Vertical Navigation Control will be the Organism, combining everything into one.

Navigation Link Icon

This Control is basically a Container, with an ImageViewer inside. Technically, this could be just an ImageViewer subclass, but using a WebContainer we can also specify its default width and height.

It will have two computed properties:

• Active As Boolean
• IconName As String

There will also be a private ShowIcon method. Whenever you change either the Active property or IconName, the computed property will call ShowIcon.

The magic is inside ShowIcon:

Var iconColor As Color = If(mActive, Color.Black, Color.LightGray)
Var icon As String = If(mActive, mIconName + "-fill", mIconName)
IconImageViewer.Picture = WebPicture.BootstrapIcon(icon, iconColor)

The icon color will be either LightGray or Black, depending if it’s active or not. There are also a lot of Bootstrap Icons with the “-fill” suffix so we’ll use them. This will force us to only use icons which have that suffix, but we will have to live with that.

The final trick is to use the Inspector Behavior and expose our Active and IconName computed properties. Right click on NavigationLinkIcon, then click on Inspector Behavior:

From there you can enable the checkboxes and define their default value:

Now that we have the Control ready, let’s see how it works on its own:

Neat! You can reuse this Atom everywhere, including other projects.

Navigation Link Control

Combining our fresh NavigationLinkIcon, a built-in WebLabel and exposing an API, we’ll create our NavigationLink Molecule.

Create a new Container and place the items inside. Then add some computed properties:

• Active
• Caption
• IconName

Whenever the property changes, just update the underlying control.

One trick, to make the control clickable, is to add a WebCanvas on top of the other controls. Implement its Pressed event and forward it as a new “Pressed” Event Definition.

If you want to show a pointer cursor when the user moves the mouse over your control, add this line of code into the container’s Opening event:

Me.Style.Cursor = WebStyle.Cursors.Pointer

This is how it looks like in the IDE:

Let’s quickly test it:

We are getting there.

Active Link Indicator

We have most of the Atoms and Molecules created already. The Navigation Link Indicator is so simple and so tied to the Sidebar, that I don’t think creating an individual Atom for it is worth the effort.

Using a WebRectangle, with a line of two of code in its Opening event, will be enough. This is completely up to you!

Vertical Navigation Control

Now it’s time to glue the Atoms and Molecules together to make our first Organism. Create a new Container called VerticalNavigation.

Drop a WebRectangle on it. Set its Left and Top to 0, and implement its Opening event with these lines of code:

Me.Style.BorderThickness = 0
Me.Style.AddTransition("top", 0.2)

That will remove the border that comes by default with this control. It will also tell the browser to animate the rectangle whenever we change the Top position.

The rectangle background color will be a light gray, but this is again up to you.

For the API we want to expose, add these Methods:

• AddLink(caption As String, icon As String, active As Boolean = False)
• HandleLinkPressed(sender As NavigationLink)
• SetActiveLink(index As Integer)

AddLink and SetActiveLink can be left Public, HandleLinkPressed will be a Private Method.

AddLink code:

// We will create a new NavigationLink instance
// and set the properties we're receiving.
Var link As New NavigationLink
link.Caption = caption
link.IconName = icon

// For its pressed event, we will handle it
// internally in the HandleLinkPressed method.
AddHandler link.Pressed, WeakAddressOf HandleLinkPressed

// We will place it programatically in  the container.
Const padding = 10
Var linkTop As Integer = mLinks.Count * (link.Height + padding)
link.EmbedWithin(Self, padding, linkTop, Self.Width - padding, link.Height)

// A reference for this NavigationLink will be
// needed later, so we will store it internally.
mLinks.Add(link)

// Finally, if the item is active, we will
// handle it just like if it's been pressed
// by the user.
If active Then
  SetActiveLink(mLinks.LastIndex)
End If

HandleLinkPressed code:

SetActiveLink(mLinks.IndexOf(sender))
RaiseEvent Pressed(sender)

And, finally, SetActiveLink:

// Here we will loop through the NavigationLink
// references we have and enable or disable the
// Active property, depending on the index
// comparison.
For i As Integer = 0 To mLinks.LastIndex
  mLinks(i).Active = i = index
Next

// Move the visual active indicator to the
// NavigationLink position.
ActiveLinkIndicator.Top = mLinks(index).Top

Final Result

Everything is ready, drop your VerticalNavigation somewhere in your WebPage and add a few links inside its Opening event:

// Setting the third parameter to "True" will set that link as Active.
Me.AddLink("Home", "house")
Me.AddLink("Explore", "binoculars", True)
Me.AddLink("Notifications", "bell")

You should see something similar to this:

Congratulations! You’ve built a vertical navigation, with nice transitions, using some Atomic Design principles.

Code repository: https://github.com/piradoiv/vertical-navigation-example
Download the project: vertical-navigation-example

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

I’ll outline the way it works here:

• Start typing in the Filter field (1). You can enter a single item or several items names using a comma.
• As you type, the list will display the filtered matches using the default “Begins with” matching criteria. You can change the matching type using the popup menu found at the right of the Filter field (2).
• If you want more control of the items filtered, click on the Edit filter button (3). Here you’ll be able to select the items to filter, clear all or select all of them. The list will be filtered based on that criteria once the dialog is closed.

The combination of the filter criteria and matching type for the current selected stack frame and variable/object will be remembered and automatically applied again when that same object/variable is selected in the Debugger Panel. This also applies when that same project is debugged again, even at different Xojo runs.

As you can see, this debugger filter can be very helpful when there are a lot of objects and variables displayed during the app’s debugging session. No license is required to learn, develop and test your projects in the latest Xojo release! Download Xojo 2023r1 today!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Just as with Xojo’s WebChart, DesktopChart and MobileChart offer the following chart types: Line, Bar, Pie, Doughnut, PolarArea, Scatter, Bubble and Radar. You can access these charts using the Inspector Panel or via code through the Mode property. You can even change the Mode (or chart type) at runtime on Desktop and Mobile.

Line and Bar types are similar; both display sets of data that have been set to Line or Bar Modes. Display as many data sets as you need in your DesktopChart or MobileChart by setting the Mode to Line or Bar. The only difference is how these will be displayed along the x axis.

To better understand, let’s write some code in the Opening Event Handler of a DesktopChart control added to a Desktop project:

Var labels() As String
Var firstSetOfData() As Double
Var secondSetOfData() As Double
Var thirdSetOfData() As Double

For n As Integer = 0 To 9
  labels.add "LB"+n.ToString
  firstSetOfData.add System.Random.InRange(0,1000)
  secondSetOfData.add System.Random.InRange(0,1000)
  thirdSetOfData.add System.Random.InRange(0,1000)
Next

Me.mode = DesktopChart.Modes.Line
Me.Title = "Chart Example With Two Datasets"
Me.AddLabels labels

Var DS1 As New ChartLinearDataset("DS1", Color.Blue, True, firstSetOfData)
DS1.ChartType = ChartLinearDataset.ChartTypes.Line

Var DS2 As New ChartLinearDataset("DS2", Color.Red, True, secondSetOfData)
DS2.ChartType = ChartLinearDataset.ChartTypes.Bar

Var DS3 As New ChartLinearDataset("DS2", Color.Green, True, thirdSetOfData)
DS3.ChartType = ChartLinearDataset.ChartTypes.Bar

Me.AddDatasets DS1, DS2, DS3

This is how it will look when the Chart has been set to Line, displaying three data sets: one of which has been set to Line and the other two to Bar:

As you can see, when the ChartType is Line, the data sets that are set to Line start drawing at the origin of the X axis, where the labels are also drawn for each column of data. This also happens when drawing data sets whose ChartType is set to Bar; thus, the first bar on the first column has half the width.

Below shows the same data sets but the ChartType is Bar. Now the Bar data sets overlay the position for the labels drawn along the X axis (they are centered on each column), and also have full the width. However, because of that, the data set whose ChartType is set to Line starts drawing at half the width of the column.

You can add as many new data sets as you want, remove them, update their values, color, etc. The chart will update to reflect the changes, including the minimum and maximum values displayed in the Y axis. Keep in mind, if a chart’s Mode has been set to Line or Bar it will only display data sets created as ChartLinearDataset (by default they are set to the Line ChartType). WebChart will behave the same, starting with Xojo 2023r1.

One difference to note when using ChartLinearDataset is that you can set the Transparency property ranging from 0 (fully opaque) to 100 (fully transparent), as well as the CornerSize when the ChartLinearDataset ChartType is set to Bar.

ChartDataset and Chart Modes

I already showed you that a chart set to Line or Bar only displays data sets created from the ChartLinearDataset class. A similar rule applies when the chart is set to other Modes. For example, Pie, Doughnut, PolarArea or Radar charts only display data sets created from the ChartCircularDataset class.

• In the same vein, Scatter and Bubble charts only display data sets created from the ChartScatteredDataset class.

DesktopChart and MobileChart, additional Properties

DesktopChart and MobileChart offer additional customisation properties. For example, you can set the font, font size and font color for the title, legend, labels and values on the Y axis.

When setting the maximum font size used for the drawing of the Y axis values based on the chart control instance size (height), if the height of the control is not enough to display the values at the specified font size, it automatically adjusts.

Other properties to further customize the look of the chart include BackgroundColor and GridColor.

Tip: You may want to set the color to Color.Clear if you want your charts to be drawn or “visible”, like if you plan to layout the chart control on top of other UI controls.

In addition, you can control whether or not to display that popup that shows the underlying value as the user moves the cursor (or while dragging their finger, on iOS). This is done through the AllowPopover property (True, by default).

Set the background and text color in the Popover using the PopoverBackgroundColor and PopoverTextColor properties. These expect a ColorGroup instance, so they can adjust when the control is in Light or Dark Mode.

Getting informed

As you may expect from their WebChart counterpart, DesktopChart and MobileChart offer a Pressed event handler to receive the index and dataset instance over which the user clicked/tapped.

Because the chart control can handle different ChartDatasets you’ll probably want to cast the received ChartDataset instance received in the Pressed handler to the right one before proceeding with any actions that are not common to all kind of ChartDatasets.

Draw it!

You can call the DrawInto method on a chart, provide the expected graphic context and also the left and top values to proceed with the drawing. For example, this is what a DesktopChart looks like when drawn on a Picture of the same size:

It is also possible to render the chart to PDF in a vectorial way using the AddChart method on a PDFDocument instance. The parameters this method expects are the chart instance itself, the X and Y values (where it will be placed in the current PDF page), and the width and height values for the rendering.

For example, this code will create a PDF file in the Desktop with the same height value of the chart instance, with the width set to the width of the page, minus the margins:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
d.AddChart(chart1, 20, 20, g.Width-40, chart1.Height )
d.Save(SpecialFolder.Desktop.Child("ChartPDF.PDF"))

In summary

As you can see, now it is possible to add Graphical Charts to your Desktop and iOS projects with the same ease and in the same way it is already possible on web projects, plus some more customization options. Watch a quick video on this topic. No license is required to learn, develop and test your projects in the latest Xojo release! Download Xojo 2023r1 today!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Starting with Xojo 2023r1 you can now do this in the Xojo Code Editor.

To swap lines, put the cursor on a line and press Option+Up Arrow (Mac) or Alt+Up Arrow (Win/Linux) to move the line up in the code. Press Down arrow to move down. Here’s a quick view of how this looks:

It also works with a selection:

To duplicate a line, put the cursor on the line and press Option+Shift+Down Arrow (use Alt instead of Option on Windows/Linux):

This also works with a selection:

I hope these new commands can make your time in the Xojo Code Editor more productive!

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

Starting with Xojo 2022r3, when importing a Module it will carry all the related stuff hanging from the root Module, that includes everything you could expect from that operation. When importing that item in the project it will not be done as an external item, but added to the project.

As you can see in the animations above, there is a significant improvement between importing modules using Xojo 2022r3 and later! Check it out yourself.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

The best thing is that implementing this feature in your Xojo Web projects is really easy to do, and extremely flexible to set-up! Just drag and drop the WebChart control from the Library to your page (or ContainerControl) layout, set the Mode (type) of the chart you want to use and other properties in the Inspector Panel and you’re almost done.

Then, add your DataSet instances for your chart to display. Every one of these DataSets just needs to receive the Label to use, the data to display and the colors associated with each value or datapoint. For example, the following snippet of code creates a new WebChartCircularDataSet (WebChartLinearDataset and WebChartScatterDataset are other DataSet classes available, each of these use their own set of parameters in the Constructor):

Var sales() As Double = Array(12500.0, 30200, 25600, 15800)
Var colors() As Color = Array(Color.Orange, Color.Brown, Color.Purple, Color.DarkGray)
Var ds As New WebChartCircularDataset("Test", sales, Colors)

Every DataSet can be configured so it can fill or not fill the graphical object in the chart representing the value, and also associate another object with it via the usual Tag property.

Once we have a DataSet in place, we can add it to the chart simply calling the AddDataSet method on the WebChart instance. You can also add it to a specific position index or even remove a DataSet from the currently available ones in the WebChart instance. In this case T is the variable pointing to a WebChart:

T.AddDataset(ds)

Of course it is also possible to add labels to the WebChart itself. For example, if our DataSet has a total of four values, then we probably would want to add the same amount of labels to the chart instance:

T.AddLabels("Q1", "Q2", "Q3", "Q4")

In addition, one visually appealing thing is that the WebChart instance will animate the presentation of the dataset values; something it will do again every time we add a new DataSet to it. It is also possible to disable this behavior for the WebChart both via code and using the Inspector Panel.

Of course, you can add new DataSets to the WebChart once it is already shown in the webpage if you need to. But what you can’t do at runtime is changing the Mode (or type) of the WebChart itself. That is, if you did set a WebChart instance with the Mode set to Line, then you can’t change the mode via code to Bar.

All in all, I really think this is one of the (many) exceptional features introduced with Web 2.0 that will make your web apps shine even more and without much effort! Definitively, the icing on the Pie.

Questions? Ask me about Xojo programming on Twitter @XojoES or on the Xojo Forum.

As an example, let’s say we desperately need to add transparency to one of your application windows. Here is how to proceed.

Find the Native API Documentation

You need to get to the right documentation for each native API.

COCOA

The source for Cocoa API is https://developer.apple.com/. Since we are looking for a window functionality, NSWindow is the class we need to review this, in which we’ll find our target ObjC method:

- (void)setAlphaValue:(CGFloat)windowAlpha

WIN32

The source for Win32 API is http://msdn.microsoft.com. Again, we want to focus on window functionalities, http://msdn.microsoft.com/en-us/library/windows/desktop/ms633540(v=vs.85).aspx in which we’ll find our target C function:

BOOL WINAPI SetLayeredWindowAttributes(In HWND hwnd,
                                       In  COLORREF crKey,
                                       In  BYTE bAlpha,
                                       In  DWORD dwFlags);

GTK

The source for GTK API is http://developer.gimp.org/api/2.0/gtk/. Here again, we want to review functions related to GTKWindow http://developer.gimp.org/api/2.0/gtk/GtkWindow.html, in which we’ll find our target C method:

void gtk_window_set_opacity (GtkWindow *window, gdouble opacity);

Map to Xojo Code

In order to avoid wasting time understanding how these methods/functions work in real situation, it’s always efficient to google around to figure out how they are implemented in native code. There are tons of sample code you can review via Google. This way, you’ll figure out our Win32 call need an other one in order to work correctly: http://msdn.microsoft.com/en-us/library/windows/desktop/ms633591(v=vs.85).aspx declared this way:

LONG WINAPI SetWindowLong( _In_ HWND hWnd, _In_ int nIndex, _In_ LONG dwNewLong);

Most of the tricky part of using Declares is the ability to convert a C/C++/ObjC type to a type Xojo can handle. Fortunately, Xojo Documentation helps a lot. It provides detailed information about how to define a Declare, and a very handy types correspondences table.

Let’s start with Cocoa

Native, Objective-C method:- (void)setAlphaValue:(CGFloat)windowAlpha

CGFloat (in that case, possible values are 0.0 to 1.0) can be handled by the Xojo type Single

So our corresponding Declare in Xojo:

Declare Sub setAlphaValue Lib "Cocoa" selector "setAlphaValue:" _
  (windowRef As Integer, windowAlpha As Single)

How you call it in Xojo:

setAlphaValue(Self.Handle, 0.4) //Here self refers to our Xojo Window instance

Now let’s deal with Win32

A valuable tip to figure out how to deal with Win32 API types is to review some widely available VB code that uses Declares. Most of the time this code will work in Xojo with no or a very few changes.

Native, C/C++ functions:

LONG SetWindowLong(HWND hWnd, int nIndex, LONG dwNewLong);BOOL SetLayeredWindowAttributes(HWND hwnd, COLORREF crKey, BYTE bAlpha, DWORD dwFlags);

Corresponding Declares in Xojo:

Declare Function SetWindowLong Lib "User32" Alias "SetWindowLongA"  (ByVal hwnd As Integer, ByVal nIndex As Integer, ByVal dwNewLong As Integer) As Integer
Declare Function SetLayeredWindowAttributes Lib "User32"  (windowRef As Integer, ByVal crKey As Integer, ByVal Alpha As Byte, ByVal dwFlags As Integer) As Boolean

How you call them in Xojo:

Call SetWindowLong Self.Handle, GWL_EXSTYLE, styleCall SetLayeredWindowAttributes(Self.Handle, 0, Me.Value, LWA_ALPHA)

Finally, Linux

Native C method:

void gtk_window_set_opacity (GtkWindow *window, gdouble opacity);

Here a GTK ‘double’ (gdouble) logically corresponds to a Xojo Double.

Corresponding Declare in Xojo:

Declare Sub gtk_window_set_opacity lib "libgtk-x11-2.0.so" (windowRef As Integer, opacity as Double)

How you call it in Xojo:

gtk_window_set_opacity(Self.Handle, 0.4)

In order to get this method working, your Linux environment must run a composite manager. If not, this method will silently fail. If you want to check it before executing this method, add a Declare like this:

Declare Function gtk_widget_is_composited lib "libgtk-x11-2.0.so" (windowRef As Integer) As Boolean

So your code looks like this:

if gtk_widget_is_composited(Self.Handle) then gtk_window_set_opacity(Self.Handle, 0.4)end if

Setting up all together in your app.

Since these declares are designed to be compiled depending of the target platform, our code should be placed into pragma directives that indicate the compiler what should be taken in account depending of the current platform you are building for:

#if TargetCocoa then
 Declare Sub setAlphaValue Lib "Cocoa" selector "setAlphaValue:" (windowRef As Integer, windowAlpha As Single) setAlphaValue(Self.handle, TransparencySlider.Value / TransparencySlider.Maximum)

#Elseif TargetWin32

 dim GWL_EXSTYLE As Integer = (-20)
 dim WS_EX_RIGHT As Integer = &H1000
 dim WS_EX_LEFTSCROLLBAR As Integer = &H4000
 dim WS_EX_LAYERED As Integer = &H80000
 dim LWA_ALPHA As Integer = &H2
 dim LWA_COLORKEY As Integer =&H1

 Declare Function SetWindowLong Lib "User32" Alias "SetWindowLongA"   (ByVal hwnd As Integer, ByVal nIndex As Integer, ByVal dwNewLong As Integer) As Integer Declare Function SetLayeredWindowAttributes Lib "User32"   (windowRef As Integer, ByVal crKey As Integer, ByVal Alpha As Byte, ByVal dwFlags As Integer) As Boolean

 Dim style As Integer

 style = style Or WS_EX_LAYERED Call SetWindowLong Self.Handle, GWL_EXSTYLE, style Call SetLayeredWindowAttributes(Self.Handle, 0, Me.Value, LWA_ALPHA)

#Elseif
 TargetLinux dim wRef As Integer = Self.Handle dim opacityVal As Double = TransparencySlider.Value / TransparencySlider.Maximum

 Declare Sub gtk_window_set_opacity lib "libgtk-x11-2.0.so" (windowRef As Integer, opacity as Double) Declare Function gtk_widget_is_composited lib "libgtk-x11-2.0.so" (windowRef As Integer) As Boolean

 if gtk_widget_is_composited(Self.Handle) then  gtk_window_set_opacity(Self.Handle, opacityVal)
 else
  MsgBox "Not Composited"
 end if
#Endif