Laying out your UI
This section explains the fundamental tasks you perform as you work with components and JBuilder's visual design tools to create a user interface. If you're comfortable using controls in a graphical user interface environment, much of the material discussed here, such as selecting, sizing, and deleting components might be familiar to you.
Basic design tasks
At the simplest level, designing a user interface in Borland JBuilder consists of five types of tasks,
- Creating UI containers such as Frames, Panels, or Dialogs.
- Placing components in the containers.
- Setting component properties.
- Attaching code to component events.
- Setting container layouts and component constraints.
Starting your UI project using wizards
The first step in designing a user interface with JBuilder is to create or open a project that includes a designable container class. While almost any class is designable, the fastest way to create a UI project with such a container class is to use the Application Wizard or the Applet Wizard. If you don't already have a project open, these wizards automatically invoke the Project Wizard to create the project, then add the files to it you need to begin designing your UI.
Using the Application Wizard
- Close any open projects in JBuilder, then choose File|New and double-click the Application icon.
- The Project Wizard appears first, suggesting a default path and project name. Enter a new path and project name, or press Finish to accept the defaults.
Note: The part of the path between Jbuilder\myprojects and the project file is the equivalent of the package name that will be suggested in the Application Wizard. For example, if you create a project called JBuilder\myprojects\mypackage\myproject.jpr
, the Application Wizard will suggest using a package name of mypackage
.
For more information on packages, see Packages in Creating and managing projects.
The Project Wizard creates the following two files:
- A project file.
- An HTML file that contains default project information. You can edit this to record any pertinent information about the project you want to display. The contents of this file always display on the Source tab when the project file is selected, even if you remove the file from the project.
- Next, the Application Wizard automatically starts, consisting of two steps. Check the features you want in each step then press Finish.
The Application Wizard creates these two files:
- A startup class for your application, called Application1.java by default. This class contains the main() method for the application. At runtime, this startup class creates an instance of the UI class for the application.
- A UI class, called Frame1.java by default, that extends DecoratedFrame.
This class is your main UI container, to which you'll add UI components using the UI Designer. It uses BorderLayout for the DecoratedFrame, and contains a BevelPanel, in XYLayout, which is the drawing surface for your UI design. This class can also optionally contain a menu bar, a status bar, a toolbar, and an about box.
Using the Applet Wizard
- Close any open projects in JBuilder, then choose File|New and double-click the Applet icon.
- The Project Wizard appears first, suggesting a default path and project name. Enter a new path and project name, or press Finish to accept the defaults.
Note: The part of the path between Jbuilder\myprojects and the project file is the equivalent of the package name that will be suggested in the Applet Wizard. For example, if you create a project called JBuilder\myprojects\mypackage\myproject.jpr
, the Applet Wizard will suggest using a package name of mypackage
.
For more information on packages, see Packages in Creating and managing projects.
The Project Wizard creates two files:
- A project file.
- An HTML file with a name matching the project that contains default project information. You can edit this to record any pertinent information about the project you want to display. The contents of this file always display on the Source tab when the project file is selected, even if you remove the file from the project.
- Next the Applet Wizards starts. Press Next to accept the defaults in both Step 1 and Step 2. (You don't need to enter any applet parameters in Step 2 unless you want to.)
- In Step 3, press Finish to accept the defaults for an HTML file.
The Applet Wizard creates the following two files:
- An HTML file containing an Applet tag referencing your Applet class. This is the file you should select to run or debug your applet.
- A Java class that extends Applet. This is your main UI container, to which you'll add UI components using the UI Designer.
The wizards import all the packages necessary for designing a UI. All you need to do is select the Frame or Applet file, click the Design tab and start adding components in the UI Designer.
Opening the UI Designer
To open the UI Designer and the other visual design tools,
- Select a visually designable Java file in the Navigation pane, such as a Frame, Panel, Applet, or Dialog file.
Note: To quickly get a designable Frame or Applet file, use the Application Wizard or the Applet Wizard.
- Click on the Design tab at the bottom of the AppBrowser. The Component Tree and UI Designer display in the AppBrowser, and the floating Inspector appears at the right.
The source code is still accessible on the Source tab of the AppBrowser so you can view and edit your source code in parallel with designing your UI. Because of JBuilder's Two-way Tool, any changes made in the UI Designer or Component Inspector are immediately reflected in the source code, and vice versa.
Adding UI components to your UI
To add a component,
- Click a component on the Component Palette.
- Do one of the following:
- Click in the UI Designer to drop the component at its default size.
- Drag the component in the UI Designer to the desired size.
Dragging to a specific size is only appropriate when using XYLayout for a container. Ultimately, the layout manager for each container in your UI will determine its components' size and position. For more information on layout managers, see Using Layout Managers.
- Drop the component onto the desired container in the Component Tree. Doing this, however, gives you no control over where the component appears in the container.
Note: To add multiple instances of a component, hold down the Shift key when clicking or dragging in the UI Designer. Continue to hold down the Shift key until you are finished adding all the instances of that component. Be careful, though, to clear the selection when you are done. Click the cursor button on the Component Palette, or release the Shift key before adding the last instance of the component. Otherwise, you may inadvertently click in the Component Tree or the UI Designer and create an unwanted component.
Notice that the right side of the status bar at the bottom of the AppBrowser displays the layout information and the component name the mouse is over as you move the mouse in the UI Designer.
When you visually add a component in the UI Designer, JBuilder generates an instance variable for the component and adds it to the source code. Also, when you delete a component, the UI Designer deletes the associated lines from the code.
Example
If you create a BevelPanel, then add a Button to it, the UI Designer adds the following code to the container's declaration statement,
Button button1;
and this code to the jbInit() method, which is called from the container's constructor:
button1=(Button)Beans.instantiate(getClass().getClassLoader(),"java.awt.Button");
bevelPanel1.add(button1, new XYConstraints(45, 26, 156, 66));
Of course, the constraints for the height, width, and x,y coordinates will be different for each button.
Selecting components in your UI
Before attempting to select an existing component in your UI, be sure the selection arrow on the Component Palette is depressed. Otherwise you may accidentally place a component on your UI.
To select a single component, do any one of the following:
- Click the component in the UI Designer.
- With focus on the Designer, tab to the component (Tab = forward; Shift+Tab = backward).
- Select the component in the Component Tree.
To select multiple components, hold down the Shift key and do one of the following:
- Click the components in the UI Designer one at a time.
- Drag around the outside of the components you want to select.
As you drag, you surround the components with a rectangle, or "lasso". When this rectangle encloses all the components you want to select, release the mouse button. If necessary, you can then use Ctrl+click to individually add or remove components from the selected group.
- Hold down the Shift key or the Ctrl key and select the components in the Component Tree.
Adding components to nested containers
When your UI Design uses multiple containers nested within each other, some layouts (GridLayout, CardLayout, BorderLayout, and PaneLayout) override the selected target container and add the component to a different container than the one you intend.
For example, if you drop two panels into an existing CardLayout panel using a left click of the mouse, CardLayout assumes you want to nest the first panel inside the CardLayout panel (which is probably true), but then assumes you want to nest the second panel inside the first container (which isn't the case if you are trying to add another panel to the stack of CardLayout panels.
To override the default drop target in these cases and indicate to the UI Designer which container should actually receive the selected component,
- Select the intended target container in the Component Tree, or in the UI Designer if it is visible.
- Select the component you want on the Component Palette.
- Hold down the Ctrl key while you click or drag the component in the UI Designer.
Sizing and moving components
For many layouts, the layout manager completely determines the size of the components by constraints, making sizing in the UI Designer have no effect. However, when working with XYLayout, you can size components when you first place them in your UI, or you can resize and move components later.
To size a component as you add it,
- Select the component on the Component Palette.
- Place the cursor where you want the component to appear in the UI.
- Drag the mouse pointer before releasing the mouse button.
As you drag, an outline appears to indicate the size and position of the control.
- Release the mouse button when the outline is the size you want.
To resize or move a selected component,
- Click on the component in the UI Designer or in the Component Tree to select it.
When a component is selected, small squares, called sizing handles or nibs, appear on the perimeter of the component, and for some containers, a move handle appears in the middle of the component.
- Click on the appropriate outer handle and drag to resize.
- Click anywhere in the component and drag it any direction to move it. If the component is a container completely covered with other components, use the center move handle to drag it.
See also:
Determining the size and location of your UI at runtime
Deleting components from your UI
To delete a component, select the component in the UI Designer or the Component Tree. Press DEL.
Note: You can not undo a delete in the UI Designer or the Component Tree.
Copying and pasting components
JBuilder does not support copying and pasting UI components in the visual design tools. You have to perform copy and paste functions by editing your source code.
Grouping components
JBuilder provides a number of container components for grouping components together so they behave as a single component at design time.
For instance, you might group a row of buttons in a Panel or GroupBox to create a tool bar. Or you could use a container component to create a customized backdrop, status bar, or check box group.
When you place components within containers, you create a relationship between the container and the components it contains. Design time operations you perform on the containers, such as moving, copying, or deleting, also affect any components grouped within them.
To group components by placing them into a container,
- Add a container to the UI. If you are working in XYLayout, you can drag to size it.
- Add each component to the container, making sure the mouse pointer falls within the container's boundaries. (The status bar at the bottom of the AppBrowser displays which container your mouse is over.) You can drop a new component from the Component Palette, or drag an existing component into the new container.
As you add components, they appear inside the selected container in the UI Designer, and under that container in the Component Tree.
Tip: If you want the components to stay where you put them, change the container's layout to XYLayout before adding any components. Otherwise, the size and position of the components will change according to the layout manager used by the container. You can change to a final layout after you finish adding the components.
Adding other JavaBeans components to your class
Components that do not descend from java.awt.Component, such as menus, dialogs and database components, are treated differently from UI components during class design. They are represented on the Component Palette just like UI components, but when you add them to your class, they are visible only in the Component Tree and they use different designers. You can select them in the Component Tree to change their properties in the Inspector, or double-click on them to open the associated designer.
Adding menus
To add menus to your UI,
- Click the MenuBar or PopUpMenu component on the Component Palette.
- Drop it anywhere onto the Component Tree, or into the UI Designer. (The Component Tree will place it in a sub tree for menus and menu components.
- Double-click on the menu component in the Component Tree to open the Menu Designer.
- Add menu items in the Menu Designer.
- Attach events to the menu items using the Inspector or the Interaction Wizard, or by manually typing source code.
For more details on creating menus, see the chapter Designing Menus in the Users Guide.
Adding database components
Database components are JavaBeans components that you never see in the UI. They are objects for controlling data and are often attached to data aware UI components, such as a Grid control. These components are, however, conveniently located on the Data Access tab in the Component Palette so you can visually add them to your program.
To add a Database component to your class,
- Click the desired component on the Data Access tab of the Component Palette.
- Drop it onto the Component Tree or into the UI Designer. You will see the component appear in the "Data Access" sub tree in the Component Tree. It will not be visible in the UI Designer.
- Modify any properties and add event handlers as with other components.
For complete information about using Database components, see Developing database applications in the JBuilder Database Applications Developer Guide.
Testing the UI at runtime
When you're ready to test your program, you can simply run it, or you can run it and debug it at the same time.
To run your program without debugging,
- Load the file(s) you want to test into JBuilder. This might be one .java source file, or a project.
- Be sure the files have been saved to disk.
- Select the project file (.jpr), or a .java file in an application, or the HTML file that contains the APPLET tag in an applet.
- Choose Run|Run to run your program on the screen. JBuilder will compile and run it. Any errors during compile are displayed in an error pane at the bottom of the Content pane. If there are errors, compiling halts so you can fix the errors found and try again.
Alternatively, you can first choose Build|Make project to compile the project, then click the Run button on the toolbar.
If you get errors, runtime exceptions, or other program misbehavior, you may want to debug your program as you run it to find the problems. You do that by running the program in JBuilder's integrated Debugger.
If you want to debug your program, you need to compile it with debug information. The default property setting for a JBuilder project generates debug information when compiling. When this is selected, JBuilder generates information in your class files during compilation that will enable symbolic information to be seen when debugging.
To run your program in the Debugger,
- Load the file(s) you want to test into JBuilder. This might be one .java source file, or a project.
- Be sure the files have been saved to disk.
- Select the project file (.jpr), or a .java file in an application, or the HTML file that contains the APPLET tag in an applet.
- Choose Run|Debug, or click Run on the tool bar.
- Debug your program and correct any errors.
For more information on compiling and debugging Java programs, see:
Compiling Java programs
Using the Debugger