# Creating a widget that uses the WRTKit

To create a widget the uses the WRTKit for its user interface, start by copying the WRTKit directory from the Library directory in the WRTKit to the root directory of the widget you are making. The root directory of your widget is the directory where your Info.plist and main HTML file is located.

The main HTML file should include a script tag that loads the file WRTKit/WRTKit.js in order to include and initialize the WRTKit library in your widget. The widget typically should have no content at all between its <body> and </body> tags. You also want to include the JavaScript script file where your own widget's code is located, and you want to define some entry point function that gets called when the widget is loaded, e.g. using the onload event that you can define for the body tag. This should result in an HTML file that looks something like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>
            <title></title>
            <script type="text/javascript" src="WRTKit/WRTKit.js"></script>
            <script type="text/javascript" src="YourOwnWidgetCode.js"></script>
        </head>
        <body onload="init()">
        </body>
    </html>

In this example the code for your own widget is in a file called YourOwnWidgetCode.js and the entry point function that gets called when the widget has loaded all files is called init(). Next, we want to create that function.

All widgets that use the WRTKit need to create an instance of the UIManager class, as well as at least one view. Creating the UIManager is a simple matter of instantiating the WRTKit UIManager class. You should retain the reference to that instance in a global variable or some other place that is accessible to the code that will need to use the UIManager's services. To do this, you would first declare the global variable to hold your UIManager instance:

    // Reference to the user interface manager.
    var uiManager;

With the variable declared you can then add the following code to the init() function to create an instance of the UIManager class and retain a reference to that instance in the uiManager variable:

    // create the user interface manager
    uiManager = new UIManager();

Now that we have a user interface manager instance we can create a new view and set it to the screen. In order to be able to access that view outside the init() function, we should crate a global variable for it just like we did for the UIManager instance:

    // Reference to the main view.
    var mainView;

In this example we will create a ListView that has a unique identifier "example" and a view caption "Example View". The unique identifier can be used to set CSS rules that are targeted to a particular view. It is often not needed and can be specified as null. The view caption is shown at the top of list views and is helpful to show users what the view is for.

    // create the main view
    mainView = new ListView("example", "Example View");

We are now ready to command the view to the screen:

    // show the mainView
    uiManager.setView(mainView);

The example widget would now be displaying an empty list view with "Example View" in its view caption and would be ready for more functionality. Let's add a button to the view. You would normally do this before the view is shown. Our example button has a unique identifier "exampleButton" and text "Press me!" on the face of the button.

    // add a button to the main view
    var exampleButton = new FormButton("exampleButton", "Press me!");
    mainView.addControl(exampleButton);

The main view now contains a button. If we wanted to be informed when the button is pressed we could create a new function and register it as an "event listener". First the callback function definition:

    // Callback function that gets called when the example button is pressed.
    function exampleButtonPressed(event) {
        // popup a notification dialog when the button is pressed
        uiManager.showNotification(3000, "info", "You pressed the button!");
    }

Now that we have a function to call when the button is pressed we can register the event listener. You should write this code in the init() function, for example right after you created the button:

    // add an event listener
    exampleButton.addEventListener("ActionPerformed", exampleButtonPressed);

The same idea applies even to much more complex user interfaces. You create views and controls, add the controls to the views, command a view to be displayed using the UIManager, and get notified of user actions using event listeners that you can register to the controls.

Parent topic: Common WRTKit tasks