QuickStart Tutorial

This section is intended to serve as a "Quick Start" tutorial for learning the basics of Bajan. If you are already familiar with creating Bajan applications, then it is recommended that you skip this section and continue on with the more advanced topics and tutorials.

This tutorial will guide you through the following steps:

Getting Started

Before you can create your first Bajan application, you must start the Bajan Editor!

By this time you should have already downloaded and installed the Bajan framework. If you have successfully installed Bajan you should be able to locate the program shortcuts in your Start Menu (Windows) or in the Application directory (Macintosh).

Starting the Editor

Click Start, then choose Programs. Choose Bajan, then choose Bajan Editor. On a Macintosh, double-click the program icon.

After the Bajan Editor is started you will see a window with a new document titled "(Untitled-1)". This is a new default document that has been created for you, and contains various views for editing a Bajan application.

Editor Views

There are several views that you should be familiar with before using the Bajan Editor. Each view represents a different aspect of the Bajan application being modified. Each view is briefly described below:

Structure View

The Structure view is a hierarchical visual representation of the Bajan application model. It is a tree of objects that define all of the user interface components and behavior of the application. The root object in the structure view is always an Application object. This object can not be modified or removed. You can add new objects to the structure by right-clicking on an existing object, and selecting "Add" from the context menu. Similarly, objects can be removed by selecting "Delete" from the menu. With the exception of the Application object, objects can be re-ordered or re-parented by dragging them to a different location in the Structure view.

Additionally, the default application will always contain an empty Scene object that is a child of the Application. Scenes are used in Bajan allow multiple "screens" for user interface and graphics objects. There is always an "active" scene, which is represented by a green colored Scene icon in the Structure view. Scenes that are not active have an orange colored icon.

Properties View

When an object is selected in the Structure view, its properties are updated in the Properties view. Most of the properties can be modified and change the appearance or behavior of the object. Some properties are read-only and can note be modified. These properties are used however to provide important information about the object. When a property is changed in the Properties view, it takes an immediate effect on the object.

Console View

The Console view is used to output messages or errors from the Bajan framework. It is also possible to use the Console view for debugging purposes, by outputting messages from Script objects. This is discussed in the Scripting section of the documentation.

Layout View

The Layout view is the main content area of the Object Browser window. This is the area which is used to manipulate the user interface and graphics components. The Layout view displays visual objects that are children of the current active scene. Objects can be moved and resized by selecting them in the Layout view, and dragging the selection around the screen.

Library View

The Library view contains a list of all of the packages and objects that can be used in the Bajan application. New objects can be created in your application by dragging them from the Library view and into the Structure or Layout view.

Creating a new Bajan application

Because the Bajan Editor creates a new default application for you when it starts, you don't need to do anything else to begin creating a new application. However, if you would like to create a new Bajan application you can choose New from the File menu. This will create an untitled application and open up a new Object Browser window.

Adding an object to the application

The first thing you will want to do when creating a Bajan application is add some objects. Typically this will include creating a user interface, so lets start by adding some user interface objects the Scene.

  1. Right-click on the Scene object in the Structure view to bring up the object context menu
  2. Choose Add -> User Interface -> Panel from the menu
  3. When you add a user interface object to the scene you will see it in two locations. You will see the Panel object under the Scene object in the Structure view, as well as the graphical object in the Layout view
  4. Select the Panel by clicking on it in the Layout view, and drag it to the center of the scene
  5. Bring up the Panel editor by double-clicking on it in the Layout view. The Panel editor allows you to quickly set some of the common properties of the Panel object. It is often easier to edit an object's properties through its editor dialog, however not all of the properties may be visible. To see and edit all of the object's properties, select it in the Structure view and edit the property values in the Properties view.
  6. Click on the Background color popup chooser to change the Panel's color

Adding behavior to an object

Adding behavior to a Bajan application means adding objects that respond to events and trigger actions. For example, this might mean playing an audio file when the user clicks a button. There are several objects in Bajan that provide specific behaviors, and can be configured to execute whenever a particular event is received. Additionally, there is a Script modifier that can be used to add complex behavior, evaluate conditional expressions, process data, and generally perform functions that are not otherwise handled by the predefined objects.

The following steps add to the previous example by creating a behavior that hides the Panel object when the user clicks on it, and shows it again when the user releases the mouse button.

  1. Right-click on the Panel object in the Structure view to bring up the object context menu
  2. Choose Add -> Core -> SetProperty from the menu
  3. Double-click on the SetProperty object in the Structure view to bring up the SetProperty object editor dialog
  4. Click on the arrow next to the text field labeled Execute When
  5. Choose hostObject -> mousePressed from the menu
  6. Click on the arrow next to the text field labeled Property and choose hostObject -> visible from the menu
  7. Enter the value "false" in the text field labeled Value. (Note: you must include the quotation marks around the word false when you enter the value)
  8. Click Ok
  9. Right-click on the SetProperty object in the Structure view to bring up the object context menu
  10. Choose Copy from the menu
  11. Right-click on the Panel object in the Structure view and choose Paste from the menu. There should now be two SetProperty objects under the Panel object in the Structure view.
  12. Double-click on the second SetProperty object in the Structure view to bring up the SetProperty object editor dialog
  13. Change the Execute When value to hostObject.mouseReleased
  14. Change Value to "true"
  15. Click Ok

Testing the application

Now that you have completed the steps to create a very basic Bajan application, you will probably want to test it to make sure it is working properly. There are two ways to test your application in the Bajan Editor.

1. Instant Preview
The first way to test your application is to preview it directly in the Layout view. To do this, click on the projector icon in the Layout toolbar.

This method will instantly let you interact with the application in the Layout view. To exit preview mode, click on the projector button again. Note: When testing the application in preview mode it is important to be aware that any changes to the application will not be reverted when exiting this mode.

2. Test Application
The Test Application command runs the Bajan application in a new window. The application is not terminated until the window is closed. Unlike the Instant Preview mode, Test Application does not affect the state of application being modified in the Object Browser.

Creating a basic script

Often times it is necessary to use a script to add behavior to a Bajan application. The Script object allows you to use Javascript to perform calculations, set properties of objects, and perform other functions when this is necessary. The following example shows how to move the location of the Panel every time a key is pressed on the keyboard.

  1. Right-click on the Panel object in the Structure view to bring up the object context menu
  2. Choose Add -> Core -> Script from the menu
  3. Double-click on the Script object in the Structure view to bring up the Script editor dialog
  4. Click on the arrow next to the text field labeled Execute When and choose application -> keyPressed from the menu
  5. Enter the following in the large text area at the bottom of the Script editor dialog:

    var randx = Math.floor( Math.random() * 640 );
    var randy = Math.floor( Math.random() * 480 );

    hostObject.location = new Point( randx, randy );

  7. Click Ok

What's next?

This Quick Start guide has given you a basic idea of how to create Bajan applications using the Bajan Editor. There are of course many topics for further discussion, however one of the best ways to learn is to play! Experiment with different objects and scripts, creating new combinations of objects and behaviors. Additional documentation and tutorials will cover more advanced Bajan authoring concepts and techniques.