• The control should show previews of images and PDF documents.
• The documents to be displayed can be dragged and dropped onto the control, or opened from the standard file selection dialog.
• In the case of images, they can also be added to the control using Copy and Paste.
• In any of the above cases, the path of the file in question must be received so that future actions can be carried out.

As an additional point, since we are using Xojo, the control will be cross-platform and functional on macOS, Windows and Linux.

Download the Example Project.

Preparation

Taking into account these requirements, as well as considering that the same problem may have more than one solution, this tutorial will show you how to create a control using the Composition technique. Using this technique, several graphical interface controls will be used internally and their use will be transparent to users who use it globally, either when creating their own applications or when using the control on any desktop platform.

When it comes to creating a control using the Composition technique, the DesktopContainerControl is the best candidate. A new ContainerControl-based class would internally use the following core controls:

1. The DesktopImageWell control which is ideal for displaying images.
2. The DesktopHTMLViewer control which is ideal for displaying the preview of PDF documents.

Now, while DesktopImageWell supports displaying images directly using Drag and Drop, this is not the case with the DesktopHTMLViewer control; so if the user of the control tried to drag and drop a PDF document or image when the HTMLViewer is displaying the control, it wouldn’t work.

To solve this situation it is common to add a third control. We’ll use a DesktopCanvas that will be, at all times, the top layer regardless of which underlying control (either the ImageWell or the HTMLViewer) is displayed. Thus, the DesktopCanvas would capture the event corresponding to the user dragging a file onto the global control (the class based on ContainerControl). Since it is transparent, it will not prevent the preview of the image or PDF file to be seen in the bottom layer control, at least on macOS.

But the Canvas is not transparent on Windows, in this case we need to use conditional compilation at various points in the class to modify the user interface of the main ContainerControl so that it adds a special area located under the controls preview (ImageViewer or HTMLViewer), and which will be used by the user of the control to drag and drop the corresponding files. For this we will use an additional DesktopCanvas.

Of course, we will also have to add a button to our control that will be responsible for opening the standard file selection dialog box so that the user can choose the file to preview.

To deal with another small difference between macOS and Windows, we will add a DesktopRectangle to be used as the base layer of the control (Z axis), so that it displays the typical Focus ring when the control is active and selected.

Designing the Control

With all that in mind, start a new Desktop project in Xojo. Drag a DesktopContainer from the Library onto the Navigator. It will look like this:

With the new Desktop Container1 instance selected in the Navigator, use the Inspector Panel to change the following values:

• Name: ImagePDFContainer
• Size > Width: 220
• Size > Height: 200

Next, add the Drag and Drop area which, remember, will be shown only when the control is executed on Windows. To do this, drag a DesktopCanvas from the Library and drop it in the area of the Layout Editor corresponding to the Design Editor, placing it right under the container for our own convenience.

With Canvas1 selected, use the Inspector Panel to change the following values:

• Name: DropArea
• Position > Left: 1
• Position > Top: 221
• Position > Width: 216
• Position > Height: 100

The design should look like this:

Now, add the background layer. This is the layer that will be in charge of displaying the focus ring for the control in Windows. To do this, drag a DesktopRectangle from the Library and drop it on the ContainerControl in the Layout Editor. The ContainerControl should show a red box indicating that the dragged control will be contained as a child control in the Container itself. Next, with DesktopRectangle1 still selected in the Layout Editor, use the Inspector Panel to modify the following values:

• Name: BacktroundRect
• Position > Left: 0
• Position > Top: 0
• Position > Width: 220
• Position > Height: 200
• Locking: Lock all four padlocks.

Next, add the button responsible for displaying the standard dialog box for selecting the file to preview. Drag a DesktopPushButton from the Library and drop it onto the bottom of the Container in the Layout Editor. The Container should display a red box to indicate that the button will be added as a child control in the Container itself.

Then, with Button1 still selected in the Layout Editor, use the associated Inspector Panel to change the following values:

• Name: OpenFileButton
• Position > Left: 0
• Position > Top: 0
• Position > Width: 178
• Position > Height: 22
• Locking: Closes the left, right and bottom locks. Open the lock on the top edge.
• Mac Button Style: Recessed
• Caption: Open File…

At this point, the control layout should look something like this:

Now, add the instance of the DesktopImageViewer control responsible for previewing the images. As in previous steps, drag the DesktopImageViewer control from the Library and drop it on the Layout Editor, in the upper right part of the Container; then, with ImageViewer1 still selected, use the associated Inspector Panel to change the following values:

• Name: ImagePreviewer
• Position > Left: 238
• Position > Top: -219
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

Drag a DesktopHTMLViewer from the Library onto the free area of the Layout Editor, just below the ImageViewer added in the previous step; Then, with HTMLViewer1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: HTMLPDF
• Position > Left: 238
• Position > Top: 0
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

At this point, the control layout should look something like this:

Finally, add the overlay to be used only when the control is executed on macOS and that is responsible for capturing the action of “Drag and Drop” files by the user. Drag a new DesktopCanvas over the Container in the Layout Editor. The Container should display a red box to indicate that the new control is being added as a child of the Container itself. With Canvas1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: CanvasOverlay
• Position > Left: 1
• Position > Top: 1
• Position > Width: 218
• Position > Height: 179
• Locking: Lock all four padlocks.

To make sure that all the “layers” (order of the controls on the Z axis) are as we expect, click on the “Show Tab Order” button in the Layout Editor toolbar. If they do not match the order shown in the image below, drag and drop each element to the correct position in the list:

Add Functionality

With the design of the control now complete, it is time to add its functionality. To do this, select ImagePDFContainer in the Navigator and add the following properties along with the values indicated in the Inspector Panel:

The first will be in charge of containing the message to be displayed in the “Drag and Drop” area:

• Name: DropFileMessage
• Type: String
• Scope: Public

The second will be the property in charge of storing the reference to the file (FolderItem instance) whose image/PDF is being previewed:

• Name: FileDropped
• Type: FolderItem
• Scope: Private

The last property will be responsible for containing the color to be used as the focus ring:

• Name: FocusColor
• Type: Color
• Scope: Public

Next, add the events that the control needs to consume for its operation. With ImagePDFContainer still selected in the Navigator, add the following Event Handlers along with the associated code:

Opening:

HTMLPDF.Visible = False
ImagePreviewer.Visible = False

#If TargetWindows Then
  DropArea.Top = Me.Height - 50
  DropArea.Height = 50
  DropArea.Width = BackgroundRect.Width
  DropArea.Left = BackgroundRect.Left
  BackgroundRect.Height = BackgroundRect.Height - 50
  
  HTMLPDF.Height = BackgroundRect.Height - 2
  ImagePreviewer.Height = BackgroundRect.Height - 2
#EndIf

RaiseEvent Opening

MouseDown:

Me.SetFocus
Return True

FocusReceived:

#If TargetWindows Then
  FocusColor = Color.Blue
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

FocusLost:

#If TargetWindows Then
  FocusColor = Color.Black
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

Since the Opening event is used by our ImagePDFContainer subclass, add an event definition with the same name so that instances created from it can also add their own Opening event handler and include any additional code to execute as desired.

Then, add an additional event definition (FileDropped) that will be the one sent by the ImagePDFContainer subclass to the instances created from it, and that implement it, to pass them as a parameter the FolderItem corresponding to the file opened / dragged and dropped / or , in the case of images, that have been pasted on the control.

• Name: FileDropped
• Parameters: file As FolderItem

Since we want to support pasting images onto the control, we also need to add a MenuHandler to the ImagePDFContainer subclass. To do this, with ImagePDFContainer still selected in the Navigator, select the option Add to “ImagePDFContainer” > Menu Handler…

Use the following values in the associated Inspector Panel:

• MenuItem Name: EditPaste

And add the following code in the Code Editor associated with the Menu Handler:

Var pb As New Clipboard
If pb.PictureAvailable Then
  Var f As FolderItem = SpecialFolder.Temporary.Child("temp-pict.png")
  If f.Exists Then f.Remove
  If f <> Nil Then
    pb.Picture.Save(f, Picture.Formats.PNG)
    FileDropped = f
    PreviewFile(FileDropped)
  End If
  Return True
End If

Return False

To complete this section, add a new method to ImagePDFContainer and use the following values in the associated Inspector Panel:

• Method Name: PreviewFile
• Parameters: f As FolderItem

Add the following code in the associated Code Editor:

FileDropped = f

If f <> Nil Then
  
  If FileDropped.Name.EndsWith(".pdf") Then
    ImagePreviewer.Visible = False
    HTMLPDF.Visible = True
    
    HTMLPDF.Top = BackgroundRect.Top + 1
    HTMLPDF.Left = BackgroundRect.Left + 1
    
    #If TargetWindows Then
      HTMLPDF.Height = BackgroundRect.Height - OpenFileButton.Height
    #Else
      HTMLPDF.Height = Self.Height - OpenFileButton.Height
    #EndIf
    
    HTMLPDF.LoadPage(FileDropped)
    
  Else
    
    Var p As Picture = Picture.Open(FileDropped)
    
    If p <> Nil Then
      ImagePreviewer.Top = BackgroundRect.Top + 1
      ImagePreviewer.Left = BackgroundRect.Left + 1
      
      #If TargetWindows Then
        ImagePreviewer.Height = BackgroundRect.Height - OpenFileButton.Height
      #Else
        ImagePreviewer.Height = Self.Height - OpenFileButton.Height
      #EndIf
      
      ImagePreviewer.Image = p
      HTMLPDF.Visible = False
      ImagePreviewer.Visible = True
      
    End If
    
  End If
  
  RaiseEvent FileDropped(FileDropped)
  
Else
  HTMLPDF.Visible = False
  ImagePreviewer.Visible = False
End If

Add Functionality to Controls

Now it’s time to add functionality to the controls. Select the CanvasOverlay item in the Navigator and add the following Event Handlers along with the code given below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetWindows Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Now select the DropArea item in the Navigator and add the following Event Handlers along with the code indicated below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetMacOS Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

Paint:

#Pragma Unused areas

g.DrawingColor = FocusColor
g.PenSize = 2.0
g.DrawRectangle(0, 0, g.Width, g.Height)
g.PenSize = 1.0

If DropFileMessage <> "" Then
  
  g.DrawingColor = Color.Black
  
  Var textLength As Double = g.TextWidth(DropFileMessage)
  Var x, y As Double
  
  x = Me.Width / 2 - textLength / 2
  y = Me.Height / 2 + g.TextHeight / 2
  
  g.DrawText(DropFileMessage, x, y)
  
End If

Now select the HTMLPDF item in the Navigator and add the Event Handlers along with the code indicated below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Next, select the ImagePreviewer item in the Navigator and add the following Event Handlers along with the code below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Finally, select the OpenFileButton item in the Navigator and add the following Event Handlers along with the code indicated below:

Pressed:

Var f As FolderItem = FolderItem.ShowOpenFileDialog("")

If f <> Nil Then
  Self.PreviewFile(f)
End If

Testing the ImagePDFContainer Control

We have completed the design and added the required functionality to our control, now it is time to add an instance to the project window so we can test its operation.

Select Window1 in the Navigator so that the associated Layout Editor is displayed. Next drag ImagePDFContainer from the Navigator and drop it onto the Layout Editor, using the following values in the associated Inspector Panel:

• Size > Width: 220
• Size > Height: 200
• Locking: Lock all four padlocks
• Appearance > Allow Focus Ring: Enabled
• Behavior > Allow Focus: Enabled.
• Behavior > Allow Tabs: Enabled.

With ImagePDFContainer1 selected in the Navigator, add the following Event Handlers along with the code below:

Opening:

Me.DropFileMessage = "Drop Files Here"

FileDropped:

LastFolderItemNameLabel.Text = file.NativePath

As you can see, this is referring to the LastFolderItemNameLabel control that we have not yet added to the window layout yet; So, let’s do that.

Select Window1 in the Navigator to access the associated Layout Editor. Drag a Label control from the Library and drop it onto the bottom of the window in the Layout Editor, then use the following values in the associated Inspector Panel:

• Name: Label1
• Position > Left: 28
• Position > Top: 360
• Position > Width: 150
• Position > Height: 20
• Locking: Lock the left and bottom padlock. Unlock the top and right locks.
• Text: Last FolderItem Path:

Add a second Label from the Library to the right of the previous one, using the following values in the associated Inspector Panel:

• Name: LastFolderItemNameLabel
• Position > Left: 190
• Position > Top: 360
• Position > Width: 390
• Position > Height: 20
• Locking: Locks the left, bottom and right padlocks. Unlock the top lock.
• Text: (empty)

Run the Application

Ready! Run the application and try dragging and dropping image files (JPEG or PNG), as well as PDF files on the control. You should see the change on the fly, showing the most appropriate viewer for each type of file. It will also display the path of the file at the bottom of the window.

You can also click on the button to select the file to display or try copying images and pasting them directly on the control. If you do this, a temporary file will be created so that one of the initial requirements is satisfied: being able to continue working with the file corresponding to the image or PDF document.

As I mentioned at the beginning, this is just one of the possible implementations. I hope you have learned a few things along the way in, for example:

• Redefine Events consumed by a base class.
• Create your own Class Events and how to launch them to “pass” information to the instances created from said class.
• Capture and work with Menu Handlers.
• Use of Conditional Compilation so that certain sections of code run only on one platform or another.
• And, of course, how to make several UI controls cooperate and present themselves as a single control to the developer and end user who are going to use them.

I hope you found it interesting. You are welcome to modify and expand the project to better suit your purposes!

Have fun and keep coding with Xojo!

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

Obviously, adding the same bunch of controls again and again on each window is not the best solution; even less so when we consider the need to add the exact same code in each of these controls.

The ContainerControl is your best bet to avoid these repetitive tasks. The ContainerControl is a component half way between the available controls in the Library (inherited from the Control class) and a Window. If you look at the properties, methods and events offered by the ContainerControl you’ll find many of these are the same ones available in the Window class.

Download the Example Project for this tutorial

ContainerControl Layout

Adding other controls to a ContainerControl couldn’t be simpler. Start by adding a new ContainerControl from the Library to the Navigator (by default, it will be named ContainerControl1), select it in the Navigator to access the Layout Editor. You can use the Inspector Panel to setup the properties. Please note, control’s locks will act on the top, left, right and bottom sides of the ContainerControl they are embedded on; as opposed to using the locks on the ContainerControl itself which locks the position of the container over the top, left, right and bottom sides of the Window where the container is used.

Using ContainerControls in the Window Layout

Now that the layout of the ContainerControl is done, it’s time to add it to the Windows or Panels. Select a Window to access the associated Layout Editor and then drag the ContainerControl from the Navigator to the desired position onto the window frame displayed on the Layout Editor. Once done, that instance will be added under the Controls section for the Window in the Navigator (by default it will be named ContainerControl11 because is an instance from ContainerControl1).

Something interesting to observe is that once you add the container to the Window, you won’t be able to change the position or behavior of the embedded controls in the container from the Window Layout Editor. The controls embedded in the container are displayed as “disabled”.

Select the item ContainerControl1 in the Navigator to change the layout, add new UI controls, and change the position, size or behavior.

Since we only can add Event Handlers to the controls added to ContainerControl1, but not when those containers are added to a window or panel, how do you “communicate” with the windows using these containers? There are several approaches to achieve this. In this example, set the Scope to Public so the Window can access the controls added to a ContainerControl.

If we had added a ListBox control (default name ListBox1) to our ContainerControl1, setting its Scope property as Public in the Inspector Panel, it can be accessed using the usual dot notation. For example, from the Open Event Handler added to the Window1 item:

Me.ContainerControl11.ListBox1.AddRow("New Item")

This solves one of the communication problems; but, how can the controls embedded in a container “communicate” with the Window containing the container? That is, how do we send the value of the selected row in the ListBox1 control to the Window?

Let’s think about that scenario for a moment: the Window Window1 knows the name of the ContainerControl added to it (ContainerControl11), and also the names of the controls added to that container because their Scope has been set to Public. On the other hand, the controls know about the ContainerControl they are embedded in, but they don’t know in advance the name of the Window where such ContainerControls can be added as part of the layout. In addition, the ContainerControl knows the name of the controls added to it, but it doesn’t know in advance the name of the Window or Panels where the container can be displayed. Moreover, it is possible to add ContainerControls to a Window or Panel layout in Design Mode (in the IDE), as well as at runtime!

Considering all of this, the simple solution to communicate between the controls added to a ContainerControl and the Window or Windows that will be using that container is by adding new methods and new Event Definitions on that ContainerControl (in this example, the one named ContainerControl1). There are other techniques, but we are going to use this one in this tutorial.

Continuing with our example,  add a new method to ContainerControl1 using the following method signature:

RowSelected(value As String)

Next, with ContainerControl1 still selected in the Navigator, choose the Insert > Event Definition option in order to create a Event using the following signature:

RowSelected(value As String)

Click on the method added previously to access the associated Code Editor and type the following line of code:

RaiseEvent RowSelected(value)

The method will simply raise the defined event passing along the received value as the argument.

Now, select the ListBox1 item on the ContainerControl1 item, and add the Changed Event Handler. This is the event raised every time the user changes the selected row in the ListBox. Type the following code in the associated Code Editor:

If Me.SelectedRowIndex <> -1 Then
    Self.RowSelected(Me.SelectedRowValue)
End if

Add the Open event to the ListBox1 item, type the following code in the associated Code Editor:

For n As Integer = 0 To 10
    Me.AddRow(n.ToString)
Next

Now, add the defined event in ContainerControl1 to the ContainerControl11 instance added to the Window1 layout. Select that item and choose the Add > Event Handler option. Choose the SelectedRow event handler and confirm the selection clicking the “OK” button.

Type the following line of code in the associated Code Editor:

MessageBox("Selected value: " + value)

Of course, you can do something more useful with the received value; but this is useful enough to show how the values can be sent from the ListBox control to any window where the container can be used.

Subclassing ContainerControl

Some projects may require using several ContainerControls, and many of them may be using a ListBox. As it is when using any other class, it would be great to have both the SelectedRow method and the SelectedRow Event Definition in their own ContainerControl subclass, and they are available by default to any ContainerControl added to the project and embedding a ListBox. The good news is that it is also possible to create a subclass for a ContainerControl, as it is explained in the User Guide.

Add a new Class to the project and use the Inspector Panel to change its name to MyContainerClass and the Super field to ContainerControl.

Next, select the SelectedRow method and the Event Definition with the same name in ControlContainer1, cut them (Edit > Cut), select MyContainerClass and paste them (Edit > Paste). Both the method and the event definition are now available under MyContainerClass.

Select ContainerControl1 in the Navigator and use the Inspector Panel to change its Super field to MyContainerClass. Add a second ContainerControl from the Library to the Navigator (by default it will be named ContainerControl2). With the new item selected in the Navigator, use the Inspector Panel to change its Super field to MyContainerClass. Add the ListBox control from the Library to the layout of the new container and type the following code in the Open event for the ListBox1 item:

For n As Integer = 0 To 10
    me.AddRow(n.ToString)
Next

Add the Changed event to ListBox1 and type the following code:

If Me.SelectedRowIndex <> -1 Then
    Self.SelectedRow(Me.SelectedRowValue)
End If

Next, add the second container ContainerControl2 to the project window Window1. The layout could be similar to that of this screenshot:

Select the ContainerControl21 item under Window1 > Controls and add the SelectedRow event handler. Add this line of code to display the received value in a message box:

MessageBox("Selected value: " + value)

As you can see, both ContainerControl1 and ContainerControl21 do not include the SelectedRow method. These are inherited from their super class: MyContainerClass.

Adding ContainerControls at Runtime

Xojo also lets you add ContainerControls at runtime, something that is really interesting and makes Xojo apps flexible and powerful. Let’s do that in a simple example:

Select the Window1 item in the Navigator and delete the ContainerControl11 and ContainerControl21 items. With Window1 still selected, add a new property using the following values in the Inspector Panel:

• Name: Containers()
• Type: MyContainerClass

Add the Open event to Window1, type the following code in the associated Code Editor:

Var leftContainer As New ContainerControl1

leftContainer.Width = 200
leftContainer.LockTop = True
leftContainer.LockRight = False
leftContainer.LockBottom = False
leftContainer.LockLeft = True

leftContainer.EmbedWithin(Me, 20, 20)

Containers.Add(leftContainer)

Var rightContainer As New ContainerControl2

rightContainer.Width = 200
rightContainer.LockLeft = True
rightContainer.LockTop = True
rightContainer.LockBottom = True
rightContainer.LockRight = True
rightContainer.EmbedWithin(Me, Me.Width - 20 - rightContainer.Width, 20)

Containers.Add(rightContainer)

Run the app, change the window size and you’ll notice how the container at the right side adjusts its height and width to match the changes made in the window while the container at the left side keeps its original position.

Try to change the selected row in any of the ListBoxes. Nothing happens! As you may remember, in order to “forward” the selected row value from the ListBox to the window we needed to add the SelectedRow event handler. This is something we can’t do when adding new container instances at runtime. In order to do that we need to use the AddHandler keyword. This lets us redirect an event handler to a delegated method. Quit the app to return to the IDE and, with Window1 still selected in the Navigator, add a new method using the following signature:

ListBoxSelectedRow(item As MyContainerClass, value As String)

Notice that the first parameter will contain a reference to the instance of the MyContainerClass raising the event, while the second parameter will contain the value itself.

The only thing left is to associate the event name with the memory address of the method that will handle it for each of the Container instances added at runtime. Again, select the Open event tied to the Window1 item and change its code like so:

Var leftContainer As New ContainerControl1

leftContainer.Width = 200
leftContainer.LockTop = True
leftContainer.LockRight = False
leftContainer.LockBottom = False
leftContainer.LockLeft = true

AddHandler leftContainer.SelectedRow, WeakAddressOf ListBoxSelectedRow

leftContainer.EmbedWithin(Me, 20, 20)

Containers.Add(leftContainer)

Var rightContainer As New ContainerControl2

AddHandler rightContainer.SelectedRow, WeakAddressOf ListBoxSelectedRow

rightContainer.Width = 200
rightContainer.LockLeft = True
rightContainer.LockTop = True
rightContainer.LockBottom = True
rightContainer.LockRight = True
rightContainer.EmbedWithin(Me, Me.Width - 20 - rightContainer.Width, 20)

Containers.Add(rightContainer)

The lines of code really are interesting:

AddHandler leftContainer.SelectedRow, WeakAddressOf ListBoxSelectedRow
AddHandler rightContainer.SelectedRow, WeakAddressOf ListBoxSelectedRow

As you can see, through AddHandler we are instructing the SelectedRow event from every container instance to be handled by the ListBoxSelectedRow method added to Window1.

On the other hand, WeakAddressOf is a Xojo programming language operator allowing us to get a “weak” reference to the memory address where the ListboxSelectedRow is found so it can be invoked.

Summary

Through this tutorial we practiced some of the basics of using ContainerControls in Desktop projects: adding them to the project, using them at design time, how to forward values from the container’s controls to the window where these can be added, how to create a ContainerControl subclass that shares its method and events with any ContainerControl subclassed from it, how to add new ContainerControl instances to a window at runtime, and also how to delegate the execution of a event so it can be handled by a window method.

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

An inconvenience of this feature is that you can’t use it when the graphic controls are placed on a ContainerControl due to the way ContainerControls are implemented. The good news is that this problem has an easy solution! Read on to learn about it:

Creating Subclasses

First, create subclasses from those Framework controls you want to use as a Control Set; this also applies when creating your own graphic controls from scratch.

For that, add a new Class to a Xojo project from the Insert menu and use the Inspector to set the class name and the Parent class it is derived from. For this example, use the following values:

• Name: MMButton
• Super: PushButton

(Obviously, you can change these for any others you need.)

Creating an array to keep references to the instances

Next, we will need a data type acting as a storage reference for every instance (in our example, buttons) we want to add to our UI layout. For this, nothing is better than adding a Property to our class whose data type is an array storing objects from our class. With the created class still selected, add a new Shared Property from the Insert menu and use the Inspector with the following values:

• Name: ClassButtons()
• Type: MMButton
• Scope: Private

The fact that this is a Shared Property means that it (and its stored values) will be available for all the class instances (objects) created from the class; while the regular properties allows us to store distinct values for each class instance.

Another detail is that, in this case, we have limited the Scope for the Shared Property to Private. That means that this will be visible only from the code executed inside the class.

Setting an index for every object

Of course, we need a way to reference every instance created from the class; for example, when we need to send a message to only one of them and not to all the available instances. For this, nothing works better than setting a new Property (this time, a regular or instance Property) and assigning its data type as Integer:

• Name: ButtonIndex
• Type: Integer
• Scope: Private

Knowing how many objects are in use

We also need to know in runtime how many instances we are using. A good way to learn this is using the Open Event, so during the instance initialization it has the opportunity to add itself to the shared array and also to set its own index value.

To do that, add the Open Event Handler to the class and write the following snippet of code in the associated Code Editor:

Sub Open() Handles Open
  ClassButtons.Append Me
  Me.ButonIndex = ClassButtons.Ubound
  RaiseEvent Open
End Sub

What does RaiseEvent Open mean? Notice that we are setting our class behavior so if we are using the Open Event on it, this Event will not be available for implementation for any of the instances created from the class.

Fixing this is really simple: add a new Event Definition to the class using the following values in the associated Inspector:

• Event Name: Open

This way, RaiseEvent Open will call the Open Event to the instance and will let our class user write and execute additional code during the control initialization.

Setting the Behavior

In order to see our example in action, we need to create a method letting us direct the available instances to do something. For this example, we are going to display a simple message whose content is the Caption set to the button index passed as parameter and that has been created from our class.

As is the case with the Shared Properties, the Shared Method is the resource provided by the Xojo language that lets us set a behavior for the Class itself, instead of being called from a concrete class instance. So, add a new Shared Method to the class using the following values in the associated Inspector:

• Method Name: SayHello
• Parameter: Index as Integer

Next, write the following line of code in the Code Editor for the Shared Method:

if ClassButtons.ubound <> -1 and index >= 0 and index <= ClassButtons.Ubound then MsgBox ClassButtons(index).Caption

Testing the Class

We are set to test the class. For this, drag and drop as many instances of the class as you want from the Navigator to the Window Layout Editor (select previously a Window!). For our testing app, we also need an additional PushButton (it can be one from the standard Library) and a TextField.

The TextField will let us to write the index number whose instance we want to send the message to, while the additional button will be in charge of calling the shared method from the class, passing the index value as parameter. Add the Action Event Handler to the regular PushButton placed in the Window1 Layout, and write the following line of code:

MMButton.SayHello( TextField1.Text.val - 1)

As you can see, when we call the method we are using the name of the class and not the name from the instances.

Of course, this technique not only works when you add the UI controls to a Windows, it also works when they are placed on a ContainerControl that you want to use in your Windows layouts.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others.

*Read this post in Spanish

When I got my first modem I went online with Genie and Delphi and uploaded JumpSTART as freeware. Even though it was freeware, I got a few checks in the mail from people that liked it.

I was reminded of JumpSTART when I saw my dock getting crowed. I thought replicating JumpSTART in Xojo would be a good project for week 8 of #JustCode. Though let’s just call it JumpStart this time around.

This is what JumpSTART looked like on monochrome 640×480 screen:

JumpStart in Xojo is greatly simplified and looks like this:

The Xojo version automatically saves and loads the apps you’ve added so there was no need for separate Load/Save, Re-Read buttons. Technically they don’t have to be apps as even a document file can be launched as well.

You can right-click on an app button after you’ve added it to Rename, Change or Clear it so that also removed the need for some UI controls. And you just click on an empty button to add an app to it. When you click on a button with an app assigned, the app is launched and JumpStart hides itself.

This Xojo app demonstrates the use of a Canvas-based button, ContainerControls added dynamically to a window, and saving/loading JSON. The Canvas-based button will let me tweak the display, colors and maybe display an icon there.

You can download the project or check it out on GitLab.

As an added code treat, I’ve posted the original JumpSTart Pascal code to GitHub. FWIW, the original Pascal source is just over 1300 lines of code. The Xojo version is about 180.

Add your #JustCode project to the week 8 forum conversation.

Download and check out earlier projects:

• Week 7: Pitch Tracker
• Week 6: Bubble Popper
• Week 5: Math Quiz
• Week 4: Mini-Golf ScoreKeeper
• Week 3: Dogs Up!
• Week 2: Password Generator
• Week 1: Color Picker