Komodo User Guide

GUI Builder (Komodo Pro)

Building Dialogs
Check out the Komodo Tour

When you invoke the New Dialog or the Edit Dialog menu option in the Project Manager or the Toolbox, it launches ActiveState's GUI Builder. The GUI Builder is an application used to create graphical user interfaces, such as dialogs containing radiobuttons and list boxes. After you create the interface, the GUI Builder will generate the associated code and place it in the Komodo Editor Pane.

You will be prompted to provide a name for the project file. This project file has the extension ".ui", and will be automatically added to the Komodo Project Manager or to the Toolbox, depending on where the dialog command was invoked.

Next, you will be prompted to specify the target language. When code is generated by the GUI Builder and displayed in the Komodo Editor Pane, it will be generated in the language specified here. A widget set matching your selected language will be displayed on the Palette tab.

Top

GUI Builder Overview

Quick Overview

  • Add rows and columns by double-clicking grid lines.
  • Resize cells by dragging the grid lines.
  • Drag and drop widgets from the Palette tab to a cell in the workspace.
  • Double-click widgets in the workspace to configure their properties.
  • Use the Menu tab to create menus and add menu item widgets.
  • Select Edit|View Menus or press Ctrl+M to show or hide menus in the workspace.
  • Use the Dialog tab to manage the structure of GUI Builder projects.
  • Use the Menu tab to add cascading menus and menu items.
  • Click the green arrow button on the toolbar or select Commands|Start Test to test the interface.
  • Save the GUI to create the files in Komodo.
Top

Workspace

The workspace is used to design the GUI. See Adding and Resizing Rows and Columns and Adding Widgets to a Dialog for more about using the GUI Builder workspace.

The column and row handles at the top and the left of the workspace indicate the selected cell. When a cell is selected, the column and row handles are displayed in blue. When a single column or row handle is selected, it is displayed in red. Use the Appearance Preferences to set color and size preferences for the workspace.

Top

Toolbar

The toolbar contains buttons for the most common widget configuration options. You must select the widget in the workspace or on the Dialog tab before changing widget properties. For a description of how to use the toolbar buttons to configure basic widget properties, see Configuring Widget Properties.

From left to right, the tools are:

Save file
Widget text
Widget text size
Widget text bold and italic
Widget text alignment
Widget foreground and background color
Widget position in cell
Widget border and relief
Widget orientation (for the scrollbar widget)
Widget delete
Run or stop running interface

Top

Widget Palette Tab


Perl/Tk 8.0 Palette tab

The Palette tab is the tab displayed by default in the GUI Builder. Its contents vary depending on the language that was selected when a dialog was added to the Toolbox or Project Manager. For more about language selection, see Creating a New Dialog.

Use the Next Widget and Previous Widget commands on the Navigate submenu to move from one widget to another in the workspace.

Widget Properties

Properties vary according to the selected target language. Select File|Project Settings to view the selected target language.

  • To change the properties of an individual widget, double-click the widget in the workspace.
  • To change the default properties for a widget, double-click the widget in the Palette tab.

The settings available in the widget properties dialog box vary depending on the type of widget that is selected.

Properties Reference

A detailed reference for each of the three languages with Tk support can be found at ActiveState's ASPN Web site, or in the documentation included with each language distribution. "Tk" is a toolkit for building graphical user interfaces. It was originally developed for Tcl, but has since been adapted for Perl and Python. To view the Tk reference for a specific language, use the links below, or consult the documentation included with ActivePerl, ActivePython, and ActiveTcl. Note that the Tcl/Tk is divided into three categories: the core (Tk Manual) and two groups of extensions (BWidgets and IWidgets).

Perl/Tk

Tcl/Tk (BWidgets, IWidgets, Tk Manual)

Python/Tkinter


Top

Dialog Tab

The Dialog tab provides a hierarchical overview of a GUI Builder project. As you add controls and menus to the workspace, a structured outline of the chosen widgets is displayed on the Dialog tab. The contents of each project are displayed beneath a collapsible "Container" node that appears at the top of the tab. You can double-click the widgets on the Dialog tab to view or edit their properties.

Use commands on the Navigate submenu to determine the relationships between widgets. Select Navigate|Select Parent to highlight the parent element of a selected widget. Select Navigate|Select 1st Child to highlight the widget that is one level below the selected element in the project hierarchy. Note that these commands are only available if you select a widget that has a "parent/child" relationship with one or more other widgets.


Top

Menu Tab

Use the widgets on the Menu tab to add cascading menus and menu items to a GUI. Just as the Dialog tab provides a hierarchical overview of the controls and buttons in a dialog, the Menu tab displays the menus and menu options that make up the menu bar in a GUI Builder project. Select Edit|View Menus to display the menus at the top of the workspace. The available menu widgets are (from left to right) "cascade", "command", "separator", "checkbutton", and "radiobutton". For directions on adding menu widgets to the workspace, see Adding Widgets to a Dialog.

Add drop-down menus and menu items to your GUI using the widgets on the Menu tab. Select Edit|View Menus to display menus in the workspace.


Top

Status Bar

The status bar displays warnings, progress messages and diagnostics. Help messages are displayed only if Show Statusbar Help is selected in GUI Builder Preferences. Help messages are displayed for the object under the current cursor position. In addition, when you drag a widget or resize handle, the status bar displays the grid position or size.



Top

GUI Builder Preferences

General Preferences

  • Insert if widget dropped on gridline: If this option is enabled, a widget is automatically inserted in a new row or column when you drop the widget on a grid line. If this option is not enabled, the GUI Builder will ignore widgets dropped on grid lines.
  • Confirm saves before test: If this option is enabled, you will be prompted to save changed files before you can test the application.
  • Confirm widget delete: If this option is enabled, you will be prompted to confirm that you want to delete a widget in the workspace.
  • Autosave on quit: If this option is enabled, changed files will be automatically saved. Otherwise, you will be prompted to save changed files.
  • Mouse Gravity: This setting determines how far the mouse pointer must move to invoke the action. Set the value lower to make the mouse more responsive, and higher to give the mouse more tolerance.
  • Show Tooltips: If this option is enabled, yellow pop-up hints will be displayed when you hover the mouse pointer over an object.
  • Show Statusbar Help: If this option is enabled, usage tips will be displayed in the bottom right corner of the GUI Builder window.

Appearance Preferences

  • Selection Color: When a widget or grid line is selected (by clicking on it), it will be outlined in the color specified here.
  • Grid Background: This setting specifies the color of grid background.
  • Active Over Color: When you hover the mouse pointer over a grid line, the line will change to the color specified here.
  • Frame Background: Set the color for the background of the frame widget.
  • Show Grid Lines: If this option is enabled, grid lines will be displayed. Alternatively, click the button at the intersection of the row and column handles (top left corner of the workspace) to toggle grid lines on and off.
  • Grid Line Thickness: Set the thickness of the grid line.
  • Default Grid Spacing: When you create a new GUI, cells will be created by default with the pixel size specified here.
  • Control Points Size: Set the size of the Widget Resize Handles.
Top

Using the GUI Builder

Creating a New Dialog

Dialog projects can be added to a project in the Project Manager, or to the Toolbox. In the Project Manager, right-click the project name or a folder within a project and select Add|New Dialog. Alternatively, from the menu, select Project|Add|New Dialog.

In the Toolbox, right-click the Toolbox tab or a folder within the Toolbox, and select New Dialog. Alternatively, from the menu, select Toolbox|Add|New Dialog.

When you invoke the GUI Builder, you will be prompted for the following information:

  1. Specify Dialog Project File: the files related to the dialog are stored in a project file with a ".ui" extension.
  2. Specify Target Language: the GUI Builder can generate code in various languages and language versions:

    • Perl/Tk (8.0)
    • Perl/Tk (8.4)
    • Tcl/Tk (8.3)
    • Tcl/Tk (8.4)
    • Python/Tkinter (8.3)
    • Python/Tkinter (8.4)


  3. Click OK. The GUI Builder will load.

When you save a new dialog in the GUI Builder, the following items will be created in either the Toolbox or the Project Manager (depending on where the New Dialog command was invoked):

  • Dialog.ui Project File: the name you specified for the dialog will be suffixed with ".ui. This dialog project file will contain two files:
    • Dialog.<language>: edit this file to add functionality to widgets.
    • Dialog_ui.<language>: this file is automatically generated by the GUI Builder, and should not be modified.
Top

Modifying an Existing Dialog

To modify the graphical properties of the dialog, right-click the project file (with the ".ui" extension) and select Edit Dialog. This will launch the GUI Builder and load the project. Code within the sections described in Adding Code to a Dialog will not be affected by modifying the graphical properties of a dialog.

Top

Adding and Resizing Rows and Columns

When you launch the GUI Builder, the workspace contains a default grid with two rows and two columns. You can create a new dialog with this default grid, or you can modify the default grid using the options described below.

Adding Rows and Columns

  • Add a Row or Column: click on a grid line, then press the Insert key. Alternatively, double-click the grid line.
  • Add a Row and a Column: click in a grid cell, then press the Insert key.

Deleting Rows and Columns

  • Delete a Row or Column: click on a grid line, then press the Delete key. Rows and columns cannot be deleted if they contain a widget.
  • Delete a Row and a Column: click in a grid cell, then press the Delete key. Rows and columns cannot be deleted if they contain a widget.

Resizing Rows and Columns

  • Configure Row and Column Size, Weight and Widget Padding: click in a grid cell, then select Edit|Row & Column Properties. Use this dialog to change size, weight and the padding around widgets.
  • Resize Row or Column: click and drag a grid line.

Straddling Rows and Columns

Sometimes you may need to resize a grid cell so that it spans multiple columns or rows. Note that straddling rows and columns is only possible when the grid cell that you want to expand contains a widget and the adjacent cells do not contain widgets. To straddle rows or columns:

  1. Click to select the cell containing the widget.
  2. Hover the cursor over one of the resize handles. The cursor will change to an arrow pointing towards a line.
  3. Click and drag across the adjacent cells.

Adding Widgets

To add a widget to a dialog from the Palette tab:

  • On the Palette tab, click the desired widget, and drag it into a cell in the workspace.

To add a widget from the Menu tab:

  1. Click the MENU container on the Menu tab or, if Edit|View Menus has been selected, click New Cascade at the top of the workspace, to add a new menu to the GUI.
  2. Select a top-level "menuitem" on the Menu tab to make the Menu widgets available. Use the "cascade", "command", "separator", "checkbutton", and "radiobutton" menu item widgets to create menus.

Deleting Widgets

To remove a widget or menu item from the workspace, select it and click the delete button on the toolbar for widgets, or click the delete button on the Menu tab for menu items.

Configuring Widget Properties

To configure basic widget properties:

  1. Select the widget in the GUI Builder workspace. The associated options will become available on the toolbar.
  2. Use the controls on the toolbar to edit widget properties.

To configure advanced widget properties:

  • Select the widget in the GUI Builder workspace, then double-click it or select Edit|Widget Properties to display a widget properties dialog box.

Resizing a Widget

  • To make a widget resizable, click the column or row handle once to select, then again to toggle the resizable setting. When the arrows on the handle point outwards, the widget will be resizable. Note that this characteristic only has an effect if the widget is configured to adhere to two (or four) sides of the cell. (The scrollbar widget is resizable by default.)
  • To make a widget span rows or columns, point the mouse at the edge of the widget and drag the widget resize handle when the mouse pointer changes (grid lines spanned by the widget will disappear).

Attaching Scrollbars to a Widget

  • To attach scrollbars to widgets, first insert the desired widget and scrollbar in the workspace. Then select the widget, and select Commands|Attach Scrollbars. You will be prompted to specify which scrollbars you wish to attach. Scrollbars can only be attached to scrollable widgets.

Loading a GUI Builder Project into a Frame Widget

  • Load Project Into Frame: This option becomes available on the Commands menu when a "frame" or "labelframe" widget is added to the workspace. Select Commands|Load Project Into Frame to navigate to a GUI component contained in another GUI Builder project (.ui) file, and then load it into the selected frame. This feature is particularly useful if you have an interface component that you want to insert repeatedly in your GUI projects.

Adding Code to a Dialog

To modify the functions within the dialog, open the Dialog.<language> file, (where "Dialog" is the name of the project, and "<language>" is the standard language suffix) located beneath the dialog project file. Do not edit the Dialog_ui.<language> file, as this file is automatically generated by the GUI Builder, and therefore changes you make could be lost. Note, however, that code entered within the following sections will be preserved, even if the dialog is subsequently modified:

  • Tcl: proc sections
  • Perl: sub sections
  • Python: def sections

You can open the callback file by selecting Open File from the Projects context menu, or by double-clicking the filename on the Projects tab. Comments included in the callback file indicate where to insert callback code and user code.

Top

Testing the GUI

  • To run the application, click the green arrow button on the toolbar, or select Commands|Start Test.
  • To stop a running application, click the red stop button on the toolbar, or select Commands|Stop Test.
Top

Viewing Code in the Komodo Editor

When you save the GUI in the GUI Builder, corresponding dialog project and language files will be created in Komodo, either in the Project Manager or the Toolbox, depending on where the New Dialog command was invoked.

To display the code in the Komodo editor, select Commands|View Code. Alternatively, in Komodo, open the Dialog.<language> file beneath the dialog project.

Top