Now, we’re going to tackle another key feature: customizable text alignment. By the end of this tutorial, you’ll be able to set the button’s text to align left, center, or right, and we’ll introduce a small amount of padding to keep the text from touching the edges when it’s not centered. This approach uses a strongly typed Enumeration to ensure we only accept valid alignment values, maintaining the high quality of our custom control.

1. Define the Text Alignment Options

To make our alignment property easy to use and type-safe, we will define a new enumeration inside the CanvasButton class.

Inside your CanvasButton class, go to Insert > Enumeration and add the following:

  Left = 0
  Center = 1
  Right = 2

2. Add New Properties for Alignment and Padding

Next, we need two new properties in the CanvasButton class to store the selected alignment and the padding value.

The TextAlignment property will use our new TextAlign enumeration, and, crucially, it defaults to TextAlign.Center.
The TextPadding property provides an adjustable inner margin, which is especially important for left and right alignment.

Public Property TextAlignment As TextAlign = TextAlign.Center
Public Property TextPadding As Integer = 8

3. Update the Paint Method

The core of this change happens in the Paint event handler. We need to modify the logic that calculates the horizontal position of the text (tx) to respect the value of our new TextAlignment property.

Locate the Paint event and replace the existing code with the following:

Sub Paint(g As Graphics, areas() As Rect) Handles Paint
  #Pragma unused areas
  
  // Use the custom CornerRadius property.
  Var currentCornerRadius As Integer = CornerRadius
  
  // Declare variables for the colors used in drawing.
  Var currentBgColor As Color
  Var currentBorderColor As Color
  Var currentTextColor As Color
  
  // Determine colors based on the button's current state (enabled, pressed, hovered).
  If Enabled Then
    If IsPressed Then
      // Use highlight color if pressed.
      currentBgColor = HighlightColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    ElseIf IsHovered Then // Check for hover only if not pressed
      // Use hover color if hovered.
      currentBgColor = HoverColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    Else
      // Use the custom background color for the default state.
      currentBgColor = BackgroundColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    End If
  Else
    // Use appropriate system or standard gray colors for the disabled state.
    currentBgColor = Color.LightGray
    currentBorderColor = Color.Gray
    currentTextColor = Color.DisabledTextColor // Use system disabled text color
  End If
  
  // Set the drawing color and draw the background shape with rounded corners.
  g.DrawingColor = currentBgColor
  g.FillRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)
  
  // Set the drawing color and pen size for the border.
  g.DrawingColor = currentBorderColor
  g.PenSize = 2
  // Draw the border shape just inside the background rectangle.
  g.DrawRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)
  
  // Draw the focus ring
  If IsFocused And AllowFocusRing Then
    g.DrawingColor = Color.HighlightColor
    g.PenSize = 1
    g.DrawRoundRectangle(2, 2, g.Width-4, g.Height-4, CornerRadius-2, CornerRadius-2)
  End If
  
  // Enable anti-aliasing for smoother text rendering.
  g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
  g.AntiAliased = True
  // Calculate the width and height of the button text.
  Var tw As Double = g.TextWidth(ButtonText)
  Var th As Double = g.TextHeight
  // Calculate the X position to center the text horizontally.
  // Updated: compute X based on TextAlignment (Left, Center, Right) while preserving centered behavior as default.
  Var tx As Double
  Select Case TextAlignment
  Case TextAlign.Left
    tx = TextPadding
  Case TextAlign.Right
    tx = g.Width - tw - TextPadding
  Case TextAlign.Center
    tx = (g.Width - tw) / 2
  End Select
  // Calculate the Y position to center the text vertically, with a small adjustment.
  Var ty As Double = (g.Height + th) / 2 - 3
  // Set the drawing color for the text.
  g.DrawingColor = currentTextColor
  // Draw the button text at the calculated centered position.
  g.DrawText(ButtonText, tx, ty)
End Sub

The magic happens at line 60

4. Inspector Integration

If you want the alignment to be easily adjustable in the Xojo Inspector, you should expose the TextAlignment and TextPadding properties. For TextAlignment, because it uses an Enumeration, Xojo will automatically display a helpful dropdown menu with Left, Center, and Right options once you expose it through the Inspector Behavior editor.

• Right-click the CanvasButton class in the Project Navigator.
• Select ‘Inspector Behavior…’
• Scroll through the property list and check the checkboxes for both TextAlignment and TextPadding.

Try It Out

You can now set the text alignment directly in the code or via the Inspector.

For example, to set alignment in code:

// Set the button to right-aligned text
MyCanvasButton.TextAlignment = CanvasButton.TextAlign.Right

Since the default value for TextAlignment is Center, no existing code needs to be modified, and all your current custom buttons will continue to render perfectly centered unless you explicitly change the alignment property.

Hope this update was useful.

You can grab the latest source on GitHub: GitHub – CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

• Tab to the button
• See a neat focus ring when it has focus
• Grab focus on click

1. Track the Focus State

Add a private property to keep track of whether the button has focus:

  Private IsFocused As Boolean = False

2. Respond to Focus Events

Implement FocusReceived and FocusLost so we can set/clear the flag and force a redraw:

  Sub FocusReceived()
    If Enabled And AllowFocusRing Then
      IsFocused = True
      Refresh(False)
    End If
  End Sub

  Sub FocusLost()
    If Enabled And AllowFocusRing Then
      IsFocused = False
      Refresh(False)
    End If
  End Sub

3. Grab Focus on Mouse Click

Modify your MouseDown to call SetFocus. Now clicking the button also gives it focus immediately:

  Function MouseDown(x As Integer, y As Integer) As Boolean
    #Pragma unused x
    #Pragma unused y

    If Enabled Then
      IsPressed = True
      SetFocus       // ← new
      Refresh(False)
      Return True
    Else
      Return False
    End If
  End Function

4. Draw an Inset Focus Ring

In the Paint event, after drawing the border, add:

// … after the border code …
If IsFocused And AllowFocusRing Then
  g.DrawingColor = Color.HighlightColor
  g.PenSize = 1
  // Inset by 2px so it sits inside the border
  g.DrawRoundRectangle(2, 2, g.Width-4, g.Height-4, CornerRadius-2, CornerRadius-2)
End If

5. Enable Canvas Focus

By default, DesktopCanvas won’t accept focus, so make sure to check AllowFocusRing in the Inspector when you drop CanvasButton onto a window.

Try It Out

1. Run the app:
   • Tab to the button → you’ll see the focus ring

What’s Next?

Stay tuned for more awesome updates!

You can grab the latest source on GitHub: GitHub – CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Now, let’s make the CanvasButton control even easier to use in the Xojo IDE by leveraging the Inspector Behavior feature. This allows you (and anyone using your control) to configure its appearance and behavior at design time, right in the Properties panel.

Why Inspector Behavior Matters

When you create a custom control, its custom properties will not appear in the Inspector by default. Inspector Behavior lets you choose which properties are shown and how they’re grouped. This makes your control feel polished and professional, and saves users from digging into code to tweak settings.

Step 1: Open Inspector Behavior

To customize Inspector options for your CanvasButton:

1. In the Xojo IDE, select the CanvasButton class in the Project Navigator.
2. Right-click it and choose Inspector Behavior…

Step 2: Expose and Organize Properties

In the Inspector Behavior dialog, you’ll see a list of all public properties (inherited and custom).

• Make the following properties visible:
  • ButtonText
  • CornerRadius
  • BackgroundColor, HoverColor, HighlightColor, BorderColor, TextColor (all grouped under a custom “Button Colors” section)
• Organize properties into logical groups for clarity.

Tip: Defining default values for your properties in the class code means they will be automatically populated in Inspector Behavior. However, Xojo gives you even more flexibility. You can override these default values directly in the Inspector Behavior dialog, so you have full control over what new instances of your control will look like by default.

Step 3: Enjoy Design-Time Customization

With Inspector Behavior set up, you (or other developers) can now:

• Change the button text right in the Properties panel.
• Pick custom colors for normal, hover, pressed, border, and text states using the color picker.
• Adjust the corner radius visually.

Step 4: Best Practices and Tips

• Use clear group names (like “Button Colors”) to help users find related properties.
• Set sensible defaults for all properties in your code, but remember you can override them in Inspector Behavior.

Conclusion

With Inspector Behavior, your custom controls feel like first-class citizens in Xojo. You and others can now design beautiful, custom buttons by simply dragging, dropping, and tweaking settings in the Inspector. No code required!

Stay tuned for future parts where we’ll explore even more advanced features.

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

In this second part, we will enhance our CanvasButton by adding more customization with new properties to:

• set the button’s colors for different states (default, hovered, pressed)
• adjust the corner radius of the button
• implement a disabled state

Let’s get started!

Adding New Properties for Customization

We need to add several properties to our CanvasButton class to store the custom colors for different states, the border color, the text color, the corner radius, and the enabled state.

1. In the Project Navigator, select your CanvasButton class.
2. Go to Insert > Property (or right-click the class and select Add to “CanvasButton” > Property).
3. Add the following properties with the specified names, types, and default values:
   • Name: BackgroundColor Type: Color Default Value: &c5e2d8b
   • Name: HoverColor Type: Color Default Value: &c729fcf
   • Name: HighlightColor Type: Color Default Value: &c628eff
   • Name: BorderColor Type: Color Default Value: &c525252
   • Name: TextColor Type: Color Default Value: &ceeeeee
   • Name: CornerRadius Type: Integer Default Value: 4

These properties will hold the values that determine the button’s appearance and behavior.

Updating Event Handlers for the Enabled State

We need to modify the existing mouse event handlers (MouseDown, MouseEnter, MouseExit, MouseUp) to check if the button is Enabled before processing any mouse actions.

Select each of the following event handlers in the CanvasButton class and update the code as shown:

MouseDown(x As Integer, y As Integer) As Boolean

#Pragma unused x
#Pragma unused y

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the button is being pressed.
  IsPressed = True
  // Refresh the control to show the pressed state visually.
  Refresh(False)
  // Return True to indicate that this event was handled.
  Return True
Else
  // If disabled, do not handle the event.
  Return False
End If

MouseEnter()

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the mouse is hovering over the button.
  IsHovered = True
  // Refresh the control to show the hover state visually.
  Refresh(False)
End If

MouseExit()

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the mouse is no longer hovering.
  IsHovered = False
  // Reset pressed state if mouse leaves while pressed (prevents accidental clicks).
  IsPressed = False
  // Refresh the control to revert from the hover state.
  Refresh(False)
End If

MouseUp(x As Integer, y As Integer) As Boolean

#Pragma unused x
#Pragma unused y

// Only process if the button is enabled.
If Enabled Then
  // Check if the button was pressed down AND the mouse is still hovering over it.
  If IsPressed And IsHovered Then
    // If true, the button was successfully clicked. Raise the custom Pressed event.
    RaiseEvent Pressed
  End If
  // Reset the pressed state regardless of whether the click was successful.
  IsPressed = False
  // Refresh the control to revert from the pressed state.
  Refresh(False)
End If

In these updated event handlers, we added an If Enabled Then check at the beginning. If the button is not enabled, the code inside the If block is skipped, preventing the button from reacting to mouse interactions. We also added #Pragma unused to the parameters x and y in MouseDown and MouseUp as they are not used in the code, which helps avoid compiler warnings. In MouseExit, we added IsPressed = False to ensure the pressed state is reset if the mouse leaves the button while the mouse button is held down.

Updating the Paint Event for Enhanced Appearance

The most significant changes will be in the Paint event where we will use the new properties to draw the button based on its current state (enabled/disabled, hovered, and pressed).

Select the Paint(g As Graphics, areas() As Rect) event handler and replace its content with the following code:

#Pragma unused areas

// Use the custom CornerRadius property.
Var currentCornerRadius As Integer = CornerRadius

// Declare variables for the colors used in drawing.
Var currentBgColor As Color
Var currentBorderColor As Color
Var currentTextColor As Color

// Determine colors based on the button's current state (enabled, pressed, hovered).
If Enabled Then
  If IsPressed Then
    // Use highlight color if pressed.
    currentBgColor = HighlightColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  ElseIf IsHovered Then // Check for hover only if not pressed
    // Use hover color if hovered.
    currentBgColor = HoverColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  Else
    // Use the custom background color for the default state.
    currentBgColor = BackgroundColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  End If
Else
  // Use appropriate system or standard gray colors for the disabled state.
  currentBgColor = Color.LightGray
  currentBorderColor = Color.Gray
  currentTextColor = Color.DisabledTextColor // Use system disabled text color
End If

// Set the drawing color and draw the background shape with rounded corners.
g.DrawingColor = currentBgColor
g.FillRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)

// Set the drawing color and pen size for the border.
g.DrawingColor = currentBorderColor
g.PenSize = 2
// Draw the border shape just inside the background rectangle.
g.DrawRoundRectangle(1, 1, g.Width-2, g.Height-2, currentCornerRadius, currentCornerRadius)

// Enable anti-aliasing for smoother text rendering.
g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
g.AntiAliased = True
// Calculate the width and height of the button text.
Var tw As Double = g.TextWidth(ButtonText)
Var th As Double = g.TextHeight
// Calculate the X position to center the text horizontally.
Var tx As Double = (g.Width - tw) / 2
// Calculate the Y position to center the text vertically, with a small adjustment.
Var ty As Double = (g.Height + th) / 2 - 3
// Set the drawing color for the text.
g.DrawingColor = currentTextColor
// Draw the button text at the calculated centered position.
g.DrawText(ButtonText, tx, ty)

Let’s break down the changes in the Paint event:

• We now use the CornerRadius property instead of a static constant for drawing the rounded rectangles.
• We introduced an If Enabled Then ... Else block.
• Inside the If Enabled Then block, we have a nested If IsPressed Then ... ElseIf IsHovered Then ... Else structure. This determines the currentBgColor:
  • If IsPressed is True, currentBgColor is set to HighlightColor.
  • If IsPressed is False but IsHovered is True, currentBgColor is set to HoverColor.
  • If neither IsPressed nor IsHovered is True, currentBgColor is set to BackgroundColor.
  • The currentBorderColor and currentTextColor are set directly from the BorderColor and TextColor properties when the button is enabled.
• Inside the Else block (when Enabled is False), we set the colors to standard gray values (Color.LightGray for background, Color.Gray for border, and Color.DisabledTextColor for text) to give the button a disabled appearance.
• Finally, the drawing commands use these currentBgColor, currentBorderColor, currentTextColor, and currentCornerRadius variables.

Using the Enhanced Custom Control

Now that our CanvasButton has more customization options and supports a disabled state, let’s see how to use these features.

1. If you don’t already have an instance, drag the CanvasButton class from the Project Navigator onto a window in the Layout Editor.
2. You can now access and set the new properties programmatically. For example, in a button’s Opening event, you could add code like this:

// Customize colors
Me.BackgroundColor = Color.RGB(200, 50, 50) // A shade of red
Me.HoverColor = Color.RGB(255, 100, 100) // A lighter red for hover
Me.HighlightColor = Color.RGB(150, 0, 0) // A darker red for pressed
Me.BorderColor = Color.Black
Me.TextColor = Color.White

// Adjust corner radius
Me.CornerRadius = 10

You can experiment with different values to see how they affect the button’s appearance. To test the disabled state, you can set the Enabled property to False.

Conclusion

We’ve now taken our custom button to the next level by adding extensive color customization, adjustable corners, and a disabled state.

This project can be downloaded from GitHub at: https://github.com/xolabsro/CanvasButton

Hope you enjoyed making the button your own! While it’s much more flexible now, there might be other features we could add down the road, so stay tuned!

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

You can read more about DesktopCanvas in the Xojo Docs.

Let’s begin!

Add a Custom Class:

• In the Project Navigator, add a new Class.
• Name it CanvasButton.
• Set its Super class to DesktopCanvas.

Add Properties:

• ButtonText As String (Set Scope to Public, Default Value to "Click Me". To make this property visible in the Inspector, right-click the CanvasButton class in the Project Navigator, select ‘Inspector Behaviour…’, scroll through the property list to find the ButtonText variable, and make sure its checkbox is checked.)
• IsHovered As Boolean (Set Scope to Private, Default Value to False)
• IsPressed As Boolean (Set Scope to Private, Default Value to False)

Define Pressed Custom Event:

• Go to Insert > Event Definition.
• Name the event Pressed. This is the event that will be raised when the button is clicked.

Add Event Handlers:

• Select the CanvasButton class in the Project Navigator.
• Go to Insert > Event Handler. Add the following event handlers and paste the corresponding code into each:

MouseDown(x As Integer, y As Integer)

// Set internal state to indicate the button is being pressed.
IsPressed = True
// Refresh the control to show the pressed state visually.
Me.Refresh(False)
// Return True to indicate that this event was handled.
Return True

MouseEnter

// Set internal state to indicate the mouse is hovering over the button.
IsHovered = True
// Refresh the control to show the hover state visually.
Me.Refresh(False)

MouseExit

// Set internal state to indicate the mouse is no longer hovering.
IsHovered = False
// Refresh the control to revert from the hover state.
Me.Refresh(False)

MouseUp(x As Integer, y As Integer)

// Check if the button was pressed down AND the mouse is still hovering over it.
If IsPressed And IsHovered Then
   // If true, the button was successfully clicked. Raise the custom Pressed event.
  RaiseEvent Pressed
End If
// Reset the pressed state regardless of whether the click was successful.
IsPressed = False
// Refresh the control to revert from the pressed state.
Me.Refresh(False)

Paint(g As Graphics, areas() As Rect)

// Corner radius of the button shape.
Static CornerRadius As Integer = 4

 // Declare variables for the colors used in drawing.
Var bgColor As Color
Var borderColor As Color = Color.DarkBevelColor
Var TextColor As Color = Color.LightTingeColor

 // Determine the background color based on the button's current state (pressed or hovered).
If IsPressed Or IsHovered Then
  // Use a highlight color if pressed or hovered.
  bgColor = Color.HighlightColor
Else
  // Use the accent theme color for the default state.
  bgColor = Color.AccentThemeColor
End If

// Set the drawing color and draw the background shape with rounded corners.
g.DrawingColor = bgColor
g.FillRoundRectangle(0, 0, g.Width, g.Height, CornerRadius, CornerRadius)

// Set the drawing color and pen size for the border.
g.DrawingColor = borderColor
g.PenSize = 2
// Draw the border shape just inside the background rectangle.
g.DrawRoundRectangle(1, 1, g.Width-2, g.Height-2, CornerRadius, CornerRadius)

// Enable anti-aliasing for smoother text rendering.
g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
g.AntiAliased = True
// Calculate the width and height of the button text.
Var tw As Double = g.TextWidth(ButtonText)
Var th As Double = g.TextHeight
// Calculate the X position to center the text horizontally.
Var tx As Double = (g.Width - tw) / 2
 // Calculate the Y position to center the text vertically, with a small adjustment.
Var ty As Double = (g.Height + th) / 2 - 3
// Set the drawing color for the text.
g.DrawingColor = TextColor
// Draw the button text at the calculated centered position.
g.DrawText(ButtonText, tx, ty)

Use the Custom Control:

• Open Window1.
• Drag the CanvasButton class from the Project Navigator onto the window.

Handle the Click Event:

• Double-click the CanvasButton instance on the window layout.
• Add the custom Pressed event handler.
• Add code inside this handler: MessageBox("Custom Button Clicked!").

Run the Project:

• Run the project. Test the button by hovering, pressing, and clicking to see the visual feedback and trigger the Pressed event.

And just like that, you’ve built your own custom button! Hope you had fun following along. Keep an eye out for our next tutorials, where we’ll take this button and give it some awesome upgrades!

This project can be downloaded from GitHub at: https://github.com/xolabsro/CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

However, as your applications grow in complexity, you may encounter scenarios where more advanced logging features are required. Developers working with other programming languages often turn to frameworks like Log4J or Log4Net for flexible and powerful logging solutions. Inspired by these tools, let’s create Log4Xojo, a powerful and flexible logging utility designed specifically for the Xojo language.

With Log4Xojo, you can:

• Save logs to files for long-term storage and analysis.
• Automatically rotate log files when they grow too large.
• Log messages to multiple destinations (e.g., Debugger, system logs, and files) simultaneously.
• Filter log messages by severity to reduce noise in production environments.

Log4Xojo complements Xojo’s built-in logging methods by extending their capabilities and making it easier to manage logs in larger or more complex applications. Whether you’re a seasoned Xojo developer or coming from other tools like Log4J or Log4Net, Log4Xojo provides a familiar, robust solution for advanced logging needs.

Xojo’s Built-In Logging Methods

Xojo provides two built-in methods for logging: System.DebugLog and System.Log

1. System.DebugLog – check here for the documentation
2. System.Log – check here for the documentation

These methods are simple to use and provide an effective way to track issues during development or monitor application behavior in production environments.

1. System.DebugLog

The System.DebugLog method outputs messages to Xojo’s Message Log in the Messages Panel during development. This allows developers to generate their own logging messages to assist with debugging and testing. Additionally, System.DebugLog writes to the system log, making it viewable in tools such as:

• Console on macOS
• DebugView on Windows
• StdErr on Linux

Example:

System.DebugLog("This is a debug message.")

Key Features:

• Outputs directly to the Messages Panel in the Xojo IDE during debugging, providing real-time insight into your application.
• Also logs to the system log, which is accessible outside of the Xojo IDE for further analysis.

Limitations:

• While System.DebugLog is versatile, its output cannot be directed to custom log files within your application without additional handling.

2. System.Log

The System.Log method writes log messages to the system’s logging mechanism. This is particularly useful for monitoring application behavior in production environments, as it integrates seamlessly with system-level logging tools.

How It Works:

• On macOS and Linux: Messages are written to the system logger, typically located at /var/log. These logs can be accessed using tools like Console (macOS) or Syslog (Linux).
• On Windows: Messages are sent to the Event Logger, which can be viewed using the Windows Event Viewer.

Example:

System.Log(System.LogLevelNotice, "This is a notice message.")

Key Features:

• Integrates with the system’s logging infrastructure, allowing log messages to persist outside of the Xojo IDE.
• Useful for production environments, where logs can be reviewed using system tools like Console (macOS), Event Viewer (Windows), or Syslog (Linux).

Limitations:

• Messages may not be portable across platforms due to system-specific log storage locations.
• Not supported in mobile projects.
• On macOS, messages logged with the following levels do not appear in the system log due to a macOS limitation:
  • LogLevelDebug
  • LogLevelInformation
  • LogLevelSuccess

Why Use the Built-In Methods?

The built-in logging methods are excellent for most projects. They are simple, efficient, and integrate seamlessly with Xojo. If your project doesn’t require file logging, log rotation, or multi-destination support, these methods might be all you need.

Introducing our custom class: Log4Xojo

While Xojo’s built-in methods are excellent for many projects, some applications demand more advanced logging features. Log4Xojo is designed to complement Xojo’s built-in methods and extend their functionality to handle more complex requirements.

What is Log4Xojo?

Log4Xojo is a custom-built logging class that expands Xojo’s logging capabilities with features like:

• File Logging: Save logs to files for later analysis.
• Log Rotation: Automatically manage log file sizes and create backups.
• Multi-Destination Logging: Log messages to the Debugger, system logs, and files simultaneously.
• Log Level Filtering: Control which messages are logged based on severity (e.g., only log warnings and errors in production).
• Named Logs: Assign each log instance a unique name, making it easier to organize and differentiate log files.
• Thread-Safe Logging: Use a background thread to process logs efficiently without blocking your application.

These features make Log4Xojo an excellent choice for larger or more complex projects, as well as applications with strict monitoring or reporting requirements.

When Should You Use Log4Xojo?

Consider using Log4Xojo if your project requires:

• Persistent logging to files for long-term storage or analysis.
• Automatic log management to prevent files from growing too large.
• Logging to multiple destinations simultaneously (e.g., Debugger, system logs, and files).
• Filtering logs by severity to reduce noise in production environments.
• Thread-safe, asynchronous logging for improved performance in multi-threaded applications. By processing logs asynchronously in a background thread, Log4Xojo ensures that your application’s performance remains smooth, even when handling a large volume of log messages.

Log4Xojo is not meant to replace the built-in logging methods but to complement them. It builds on the foundation of System.DebugLog and System.Log by adding advanced features for developers who need more flexibility and control.

How to Use Log4Xojo

Using Log4Xojo is simple! Follow these steps to get started.

Step 1: Add Log4Xojo to Your Project

1. Download the Log4Xojo class file from GitHub https://github.com/xojo/log4xojo or click here to download the Xojo example project.
2. Drag the Log4Xojo class file into your Xojo project.

Step 2: Create a Log Instance

Create an instance of the Log4Xojo class. Each log requires a name, which is used to identify it and organize log files.

Var l4x As New Log4Xojo("AppLog")

Step 3: Configure the Log

Set up the logging destinations, file path, log level, and other settings. For example:

// Set destinations (Debugger and File)
l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.FileLog)

// Set the base folder for the log file
l4x.SetLogFilePath(SpecialFolder.Desktop)

// Set the log level to Warning and above
l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)

// Configure log rotation
l4x.SetMaxBackupFiles(5)
l4x.SetMaxLogFileSize(1024)

Step 4: Log Messages

Log messages with varying severity levels:

l4x.Log("Application started.", Log4Xojo.LogLevel.Info, CurrentMethodName)
l4x.Log("This is a debug message.", Log4Xojo.LogLevel.Debug, CurrentMethodName)
l4x.Log("Warning: Low disk space.", Log4Xojo.LogLevel.Warning, CurrentMethodName)
l4x.Log("Error: File not found.", Log4Xojo.LogLevel.Error, CurrentMethodName)

The optional location parameter (CurrentMethodName above) allows you to include the context of the log message, such as the method or class where it originated. This makes it easier to pinpoint the source of issues when reviewing logs.

Step 5: Stop Logging

When your application shuts down, make sure to stop logging to ensure all queued messages are processed:

l4x.StopLogging()

Use Case Scenarios for Log4Xojo

To better understand how Log4Xojo can enhance your Xojo applications, here are some practical use cases:

1. Monitoring Application Performance in Production

In a production environment, it’s essential to keep track of your application’s behavior without impacting performance. With Log4Xojo, you can:

• Log important application events (e.g., user activity, API calls).
• Use file logging to store these logs persistently for later analysis.
• Filter logs by severity to avoid unnecessary noise (e.g., only warnings, errors, and critical issues).

Example:

Var l4x As New Log4Xojo("ProductionLog")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)

// Log application events
l4x.Log("User logged in", Log4Xojo.LogLevel.Info) // Ignored (below warning level)
l4x.Log("Database connection failed", Log4Xojo.LogLevel.Error) // Logged
l4x.Log("Critical: Payment gateway unreachable", Log4Xojo.LogLevel.Critical) // Logged

Outcome: Only warnings, errors, and critical messages are logged to a file for postmortem analysis without overwhelming the log with lower-priority messages.

2. Creating a Diagnostic Tool for End Users

When troubleshooting issues reported by end users, having detailed logs can be invaluable. With Log4Xojo, you can:

• Log messages to a file on the user’s machine.
• Include optional location tags to pinpoint where issues occur in your code.
• Use log rotation to prevent log files from consuming too much disk space.

Example:

Var l4x As New Log4Xojo("UserDiagnostics")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetLogFilePath(SpecialFolder.Documents)
l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB
l4x.SetMaxBackupFiles(3)

// Log diagnostic information
l4x.Log("Application launched", Log4Xojo.LogLevel.Info, CurrentMethodName)
l4x.Log("Error: File not found", Log4Xojo.LogLevel.Error, "FileManager.LoadFile")
l4x.Log("User clicked 'Submit'", Log4Xojo.LogLevel.Debug, "MainWindow.HandleSubmit")

Outcome: You can ask users to send the log files stored in their Documents folder for review, helping you quickly diagnose and fix issues.

3. Tracking User Activity in Enterprise Applications

In enterprise applications, logging user activity is often a requirement for auditing or compliance purposes. With Log4Xojo, you can:

• Use multi-destination logging to send activity logs to both the system logs and a central log file.
• Include relevant context for each log entry (e.g., user ID, method).

Example:

Var l4x As New Log4Xojo("AuditLog")
l4x.SetLogDestinations(Log4Xojo.LogDestination.SystemLog, Log4Xojo.LogDestination.FileLog)
l4x.SetLogFilePath(SpecialFolder.Documents)

// Log user activity
Var userID As String = "User123"
l4x.Log(userID + " logged in", Log4Xojo.LogLevel.Info, "AuthManager.Login")
l4x.Log(userID + " updated profile", Log4Xojo.LogLevel.Info, "ProfileManager.UpdateProfile")
l4x.Log(userID + " attempted unauthorized access", Log4Xojo.LogLevel.Warning, "SecurityManager.CheckPermissions")

Outcome: Both system logs and a persistent file log are updated with the user’s activities, ensuring compliance and easy traceability.

4. Handling Errors and Crashes Gracefully

When an application crashes, logs are often the only way to understand what went wrong. Log4Xojo can:

• Capture error and critical logs leading up to a crash.
• Rotate logs to avoid losing older, relevant logs.
• Save logs to a file for recovery after a crash.

Example:

Var l4x As New Log4Xojo("CrashLogs")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetMaxBackupFiles(5)
l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB

Try
  // Simulate application logic
  Raise New RuntimeException("Simulated crash")
Catch e As RuntimeException
  l4x.Log("Critical error: " + e.Message, Log4Xojo.LogLevel.Critical, CurrentMethodName)
End Try

Outcome: The log files can be used to investigate the cause of the crash.

The Structure of the Log4Xojo Class

Log4Xojo includes several constants, enums, properties, and methods that provide its advanced functionality. Let’s break them down:

Constants

1. MaxQueueSize
   • Defines the maximum number of log messages that can be stored in the logging queue before processing.
   • Default: 10,000.

Enums

1. LogDestination
   • Specifies where log messages should be sent:
     • DebugLog: Logs to the Xojo Debugger using System.DebugLog.
     • SystemLog: Logs to the system’s logging framework using System.Log.
     • FileLog: Logs to a file.
     • All: Logs to all destinations.
2. LogLevel
   • Defines the severity levels for log messages:
     • Debug: Detailed debugging information.
     • Info: General informational messages.
     • Warning: Potential issues that don’t interrupt program flow.
     • Error: Errors requiring attention.
     • Critical: Critical issues that may cause application failure.

Properties

1. mLogName
   • The name of the log. This is required during initialization and is used to identify logs and organize log files.
2. mCurrentLogLevel
   • The minimum severity level of messages to log. Messages below this level are ignored.
3. mLogDestinations
   • An array of LogDestination values specifying where logs should be sent.
4. mLogFilePath
   • The file path for logs. This is automatically generated based on the log name and current date but can also be customized.
5. mMaxBackupFiles
   • The maximum number of backup log files to retain. Default: 10.
6. mMaxLogFileSize
   • The maximum size of the log file in bytes before rotation occurs. Default: 1 MB.
7. mLogQueue
   • A queue for temporarily storing log messages before they are processed.
8. mLogQueueMutex
   • A mutex used to ensure thread safety when accessing the log queue. Check mutex documentation here.
9. mLogThread
   • A background thread that processes log messages. Check thread documentation here.
10. mRunning
    • A flag indicating whether the logging thread is running.

Methods

The Log4Xojo class provides several methods to configure logging behavior and manage log messages. Let’s go through each one in detail:

1. Constructor(Name As String)

Purpose: The constructor initializes a new instance of the Log4Xojo class with a required log name. This name is used to identify the log instance and organize log files.

Usage:

Var l4x As New Log4Xojo("AppLog")

Details:

• The Name parameter is required and cannot be empty. If you pass an empty string, the class will raise an InvalidArgumentException.
• The log name is used to generate log file names (e.g., AppLog_2024-11-01.txt).

2. Log(message As String, level As LogLevel, Optional location As String = “”)

Purpose: Logs a message with a specified log level and an optional location string.

Usage:

l4x.Log("This is an informational message.", Log4Xojo.LogLevel.Info)
l4x.Log("Warning: Low disk space.", Log4Xojo.LogLevel.Warning, CurrentMethodName)

Details:

• message: The log message you want to record.
• level: The severity level of the message. This determines whether the message will be logged, based on the current log level (mCurrentLogLevel).
• location (optional): A string to provide context for the log message, such as the method or class where it originated. This is especially useful for tracing the source of issues. Using CurrentMethodName is more than enough, unless you need to specify something else.
• If the log level is below the configured mCurrentLogLevel, the message is ignored.

Example Output:

[2023-10-01 12:34:56] [INFO] This is an informational message.
[2023-10-01 12:35:00] [WARNING] [Code-Location] Warning: Low disk space.

3. SetLogDestinations(ParamArray destinations As LogDestination)

Purpose: Specifies where log messages should be sent (e.g., Debugger, system logs, files, or all destinations).

Usage:

l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.FileLog)

Details:

• Accepts one or more LogDestination values as parameters.
• Supported destinations:
  • LogDestination.DebugLog: Logs to the Xojo Debugger using System.DebugLog.
  • LogDestination.SystemLog: Logs to the system’s logging framework using System.Log.
  • LogDestination.FileLog: Logs to a file.
  • LogDestination.All: Logs to all destinations simultaneously.
• You can mix and match destinations to suit your needs.

Example:

• To log messages only to a file:l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
• To log messages to both the Debugger and system logs:l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.SystemLog)

4. SetLogFilePath(baseLocation As FolderItem)

Purpose: Sets the folder where log files should be stored.

Usage:

Var folder As FolderItem = SpecialFolder.Desktop
l4x.SetLogFilePath(folder)

Details:

• baseLocation: A FolderItem representing the folder where log files will be saved.
• The folder must exist and be writable. If the folder is invalid, the method will raise an InvalidArgumentException.
• The log file name is automatically generated based on the log name and current date (e.g., AppLog_2024-11-01.txt).

Example:

• To store logs in the Documents folder:l4x.SetLogFilePath(SpecialFolder.Documents)

5. SetLogLevel(level As LogLevel)

Purpose: Sets the minimum severity level for messages to be logged.

Usage:

l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)

Details:

• level: A LogLevel value that determines which log messages will be recorded.
• Messages with a severity lower than the set level are ignored.

Supported Log Levels:

• Log4Xojo.LogLevel.Debug: Detailed debugging information.
• Log4Xojo.LogLevel.Info: General informational messages.
• Log4Xojo.LogLevel.Warning: Potential issues that don’t interrupt program flow.
• Log4Xojo.LogLevel.Error: Errors requiring attention.
• Log4Xojo.LogLevel.Critical: Critical issues that may cause application failure.

Example: If you set the log level to LogLevel.Warning, only warnings, errors, and critical messages will be logged:

l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)
l4x.Log("This is a debug message.", Log4Xojo.LogLevel.Debug) // Ignored
l4x.Log("This is a warning message.", Log4Xojo.LogLevel.Warning) // Logged

6. SetMaxBackupFiles(max As Integer)

Purpose: Configures the maximum number of backup log files to retain.

Usage:

l4x.SetMaxBackupFiles(5)

Details:

• max: The maximum number of backup files to keep. Older backups are automatically deleted when the limit is reached.
• When the current log file exceeds the size limit (set via SetMaxLogFileSize), it is renamed as a backup (e.g., AppLog_Date_1.txt), and a new log file is created.

Example: If max = 5, the backups will look like this:

AppLog_Date_1.txt
AppLog_Date_2.txt
AppLog_Date_3.txt
AppLog_Date_4.txt
AppLog_Date_5.txt

Once the 6th backup is created, AppLog_Date_1.txt is deleted to make room for it.

7. SetMaxLogFileSize(sizeInBytes As Integer)

Purpose: Defines the maximum size of the log file before it is rotated.

Usage:

l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB

Details:

• sizeInBytes: The maximum size of the log file in bytes.
• When the log file exceeds this size, it is renamed as a backup, and a new log file is created.

8. StopLogging()

Purpose: Stops the logging thread and processes any remaining messages in the queue.

Usage:

l4x.StopLogging()

Details:

• Use this method when your application is shutting down to ensure that all log messages are written to their destinations.
• The method waits for a short period to process any remaining messages in the queue before terminating the logging thread.

Conclusion

Xojo’s built-in logging methods, System.DebugLog and System.Log, are excellent built-in tools for debugging and monitoring application behavior. They are simple, effective, and suitable for most types of projects.

For applications with more advanced requirements, the Log4Xojo class provides a powerful complement to these methods. With features like file logging, log rotation, multi-destination support, and log level filtering, Log4Xojo is the perfect solution for larger or more complex projects.

Download Log4Xojo from GitHub https://github.com/xojo/log4xojo or as a Xojo Binary Project file and start enhancing your logging workflow.

We look forward to hearing how you’re using Log4Xojo in your projects!