UserGuide

Desktop Custom Controls

From Xojo Documentation

You can create your own custom controls by subclassing built-in controls, drawing them entirely using a Canvas or by combining controls using a Container Control.

Custom Controls for Desktop Projects

Subclassing Built-in Controls

You can create your own custom controls by subclassing any of the built-in controls. For example, desktop projects do not have a “Link” control, which would be useful to open the default browser to the specified URL. To create such a control, you could start by subclassing the Label control.

  1. Drag a Label from the Library to the Navigator. This adds a new control called “CustomLabel”. Change its name to “LinkLabel”.
  2. Using the Add button on the Editor toolbar for LinkLabel, choose Property. Change the property name to “URL” with Type “String”.
  3. Using the Add button on the Editor toolbar for LinkLabel, choose Event Handler and then select the MouseDown event.
  4. Add this code:
    ShowURL(URL)
  5. Now you can drag LinkLabel from the Navigator onto a Window and set the URL property in its open event:You might also want to change its Text property to be “Wikipedia” so it is more obvious what will happen when it is clicked.

Run the project and click on the LinkLabel. Your default browsers opens to the Wikipedia web site.

Refer to UserGuide:Subclassing Examples for other examples of subclassing.

Inspector Behavior

When creating custom controls, you may want to make some of its properties changeable at design time in the Inspector. Using the LinkLabel example above, it would be better if you could set the URL property in the Inspector for the control on the layout rather than having to put code in the Open event.

Inspector Behavior for LinkLabel Control

You use the UserGuide:Inspector Behavior feature to control what displays in the Inspector. To use it, open the contextual menu for LinkLabel in the Navigator and select Inspector Behavior. This opens the Inspector Behavior dialog. In this dialog, you can control all the properties that appear in the Inspector, including any new ones that you add. If you scroll down, you will see the URL parameter. Check the box next to its name and click OK to have the property displayed in the Inspector for the control when it is on a layout. Now you can specify the URL in the Inspector and remove the Open event from the LinkLabel.

Here are the steps in general:

  1. Create your custom control.
  2. Select the proper Inspector Behavior entries to expose in the IDE.
  3. Drag and drop the custom control onto your layout.
  4. Scroll the inspector to the appropriate section (usually Behaviors) to see your exposed properties.

Other Features of the Inspector Behavior Dialog

The Inspector Behavior dialog allows you to control all aspects of what appears in the Inspector. You can:

  • Add or remove group headings: Use the “+” or “-” buttons below the list or use the contextual menu.
  • Change the order of the properties, including moving them to different groups: Drag properties around as needed.
  • Set or modify default values: Double-click in the Default Value column for the property to set or modify the default value.
  • Change whether a property is shown or hidden: Check the property to display it; uncheck it to hide it.
  • Add enumerations: Use the Enumerations control on the right to add values that the user can select from a list.

Using Subclassed Controls in Your Projects

When you've created subclassed controls, there are a couple ways you can add them to a layout. For smaller projects you may find it is fast and easy to select the destination layout project item and then drag the subclassed control from the Navigator onto the layout.

You can also find subclassed controls in the Library. If you have "Group Banners" turned on for the Library you'll find any subclassed controls in the "Project Controls" section at the end. You can drag a subclassed control that appears here onto the layout the same as you can for any of the built-in controls.

If you have a subclassed control that you do not want to appear in the Library you can "hide" it by setting a special attribute on the subclassed control. Add the HideFromLibrary attributeto the subclassed control and it will not appear in the Library.

Property Value Assignment

When you create control subclasses, the values of public properties are set in this order:

  1. They are assigned values set by the subclass itself, either in the Constructor or as defaults.
  2. The above values are overridden by default values for properties specified in the Inspector Behavior window.
  3. The above values are overridden by values changed in the Inspector.

See Also

UserGuide:OOP Design Concepts, UserGuide:Subclassing Examples, UserGuide:Desktop Container Controls UserGuide:Desktop Canvas, UserGuide:Inspector Behavior topics