Base Windows

A base window is the principal window for an application. It can contain any number of panes, which display information or provide controls. Start each application you build with a base window.

Editing the Properties of a Base Window

To edit the properties of a UI base window, select it and open its property window, shown in Figure 4-1. To do this, double-click SELECT on the window or its footer (not on its header or border). See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-1

Base Windows Scrolling List

The scrolling list at the top of the property window lists each of the base windows in the current interface. To set the properties of a base window, click SELECT on the window's name. The name is boxed to show that it's selected. The controls in the rest of the property window change to show the current settings of the selected base window.

Object Name

Object Name establishes the name that Devguide gives the base window in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the base window.

Window Parent

The base window's parent.

Label

The Label text field sets the label that appears in the base window's header.

Rectangle

The Rectangle line contains two text fields:

• W - The base window's width in pixels
• H - The base window's height in pixels

To change one of these values, select it, then type the new value. These values update automatically when you make any changes by dragging resize corners or handles.

Footer

There are two possible footer states for base windows.

• Present - Adds a footer to the bottom of the base window
• Not Present - Removes the footer from the bottom of the window

This property takes effect when you enter Test mode or after you compile code.

Size

The Size setting determines whether the base window is resizable or not.

• Adjustable - Sets the base window so the user can resize it by dragging its resize corners

• Fixed - Sets the base window so the user can't resize it

If you turn off the resize corners, you won't see them disappear until you leave Devguide and generate and compile source code for the window.

Icon

Icon contains the file name of the icon you want to attach to the UI base window. Note that you must create, name, and save your own icon before you compile the user interface code so Devguide can attach the icon when you compile the code.

Icon Label

Icon Label contains the label you want to attach to the UI base window's icon. Icon Label is optional.

Icon Type

The icon you choose to display for the base window can have a border, or be borderless.

• Normal - The base window's icon appears on the workspace as a bordered icon; that is, it is a full opaque rectangle.
• Borderless - The icon appears on the workspace without a rectangular border. To create a borderless icon, you must create and specify an icon mask to accompany your icon. This mask is essentially a shadow of your icon image. When you select the Borderless Icon Type, the Icon Mask field is enabled.

Icon Mask

Fill in Icon Mask with the name of the file containing your icon mask. The icon mask is an icon that is a silhouette of your standard icon. Any black pixels in the icon mask block background screen from showing through the standard icon. Any white pixels allow the background to show through.

Initial State

There are three possible initial states for a base window.

• Open - The window appears as an open window when you start the program.
• Iconic - The window appears as an icon when you start the program.
• Invisible - The window is invisible when you start the program.

The user interface must be set so that at least one window is initially open or iconic.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the base window.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the base window.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the base window and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Pop-up Windows

A pop-up window, like a base window, defines a section of the workspace where an application displays information, performs functions, and offers controls to the user. A pop-up window is auxiliary to the base window, and never appears as a program's primary window. Pop-up windows typically appear at the user's request to display more information or controls.

Editing the Properties of a Pop-up Window

To edit the properties of a pop-up window, select it and open its property window, shown in Figure 4-2. To do this, double-click SELECT on the window or its footer (not on its header or border). See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-2

Pop-up Windows Scrolling List

The scrolling list at the top of the property window lists each of the pop-up windows in the current interface. To set the properties of a pop-up window, click SELECT on the window's name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected pop-up window.

Object Name

Object Name establishes the name that Devguide gives the pop-up window in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the pop-up window.

Window Parent

The pop-up window's parent.

Label

Label sets the label that appears in the pop-up window's header.

Rectangle

The rectangle line contains two text fields:

• W - The pop-up window's width in pixels
• H - The pop-up window's height in pixels

To change one of these values, select it, then type the new value. These values update automatically when you make any changes by dragging resize corners or handles.

Footer

There are two possible footer states for pop-up windows.

• Present - Adds a footer to the bottom of the pop-up window
• Not Present - Removes the footer from the bottom of the window

This property takes effect when you enter Test mode or after you compile code.

Size

Size determines whether the pop-up window is resizable or not.

• Adjustable - Sets the pop-up window so the user can resize it by dragging its resize corners

• Fixed - Sets the pop-up window so the user can't resize it

If you turn off the resize corners, you won't see them disappear until you leave Devguide and generate and compile source code for the window.

Pushpin

Pushpin determines whether or not the pop-up window can remain on the workspace indefinitely.

• Out - Sets the pop-up window's pushpin in the out position when the pop-up window first appears. The window disappears when Apply is selected. Clicking SELECT on the pushpin toggles it to the In position.
• In - Sets the pushpin in the in position so the pop-up window will remain on the workspace until the user clicks SELECT on the pushpin.

Initial State

There are two possible initial states for a pop-up window.

• Invisible - The pop-up window is invisible when you start the program.
• Open - The pop-up window appears as an open window when you start the program.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the pop-up window.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the pop-up window.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the pop-up window and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Dismissing a Pop-up Window

To dismiss a UI pop-up window from the workspace to free up space, first select the window, then choose Dismiss from its Window menu or simply click SELECT on its pushpin. The window disappears from the workspace, but it still remains a part of the user interface you're designing.

Recalling a Pop-up Window

To recall a dismissed UI pop-up window, open the Pop-up Windows property window by choosing Pop-up Windows... from the Properties menu. Select the name of the pop-up window from the Pop-up Windows list; the UI pop-up window appears once again on the workspace. You can also recall all dismissed pop-up windows at one time by choosing Dismissed Windows from the View button on the Devguide window.

Tying a Pop-up Window to Other Elements

Note that when you create a pop-up window with Devguide, it is unattached to other user interface elements such as buttons. If you want the pop-up window to appear when an external event occurs, you must do one of the following:

• Use connections if your postprocessor provides appropriate built-in actions. See "Handling Events Using Connections" on page 81 for details.
• Add your own code to the code generated by the postprocessor to tie the pop-up window to actions in the user interface.

Setting a Pop-up Window's Appearance Location

Devguide does not control the pop-up window's location when it first appears. To set the location, you must specify it in your own custom code.

Control Areas

A control area is a region of a window where the program displays controls such as buttons, settings, and sliders. You must place a control area within a base window or pop-up window before you can start to place controls into the user interface.

Editing the Properties of a Control Area

To edit the properties of a UI control area, select it and open its property window, shown in Figure 4-3. To do this, double-click SELECT on the control area. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-3

Control Areas Scrolling List

The scrolling list at the top of the property windows lists each of the control areas in the current interface. To set the properties of a control area, click SELECT on the control area's name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected control area.

Object Name

Object Name establishes the name that Devguide gives the control area in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the control area.

Rectangle

The Rectangle entry contains four text fields that are used to describe a control area.

• X - The distance in pixels of the upper-left corner of the pane or control area from the left edge of the parent (containing) window
• Y - The distance in pixels of the upper-left corner of the pane or control area from the top of the parent (containing) window
• W - The control area's width in pixels
• H - The control area's height in pixels

These values update automatically when you make any changes by dragging resize corners or handles.

Show Border

The Show Border setting controls the border that appears around a control area.

• Yes - Turns on the border around the control area
• No - Turns off the border

If you turn off the border, it won't disappear while you're in Build mode, but it will disappear when you enter Test mode.

Initial State

There are two possible initial states for a control area when its parent window first appears.

• Visible - The control area appears as an open window when its parent window first appears.
• Invisible - The control area is invisible when its parent window first appears.

Menu

Press MENU on the Menu button to display the New... and Names items. Names has an attached submenu. Choose New... to open the Menu Editor Window and create a new menu. To attach an existing menu to the control area, choose the menu's name from the Names submenu, or enter the name on the line to the right of the Menu button.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the control area.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the control area.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the control area.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the control area and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Aligning Controls in a Control Area

After you add controls to a control area, you can arrange the controls any of three methods:

• Choose any of Devguide's Arrange menu items: Group and Ungroup, the Align... pop-up, or the Grid and Grid Snap submenus.
• Create groups, and arrange the group elements using the Groups window.
• Use the Align and Distribute submenus of a control area's pop-up menu. (The pop-up menu also allows you to group and ungroup.)

Canvas Panes

A canvas pane is a region of a window where the program displays graphics and where users can draw their own graphics or edit existing graphics. Each canvas pane has a boundary surrounding it. Because the canvas pane often contains a larger image (called a canvas) than it can display at once, you can add a vertical scrollbar and a horizontal scrollbar so the user can scroll through the canvas.

Editing the Properties of a Canvas Pane

To edit the properties of a UI canvas pane, select it and open its property window, shown in Figure 4-4. To do this, double-click SELECT on the canvas pane. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-4

Canvas Panes Scrolling List

The scrolling list at the top of the property windows lists each of the canvas panes in the current interface. To set the properties of a canvas pane, click SELECT on the pane's name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected canvas pane.

Object Name

Object Name establishes the name that Devguide gives the canvas pane in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the canvas pane.

Rectangle

The Rectangle entry contains four text fields that are used to describe a canvas pane.

• X - The distance in pixels of the upper-left corner of the canvas pane from the left edge of the parent (containing) window
• Y - The distance in pixels of the upper-left corner of the canvas pane from the top of the parent (containing) window
• W - The canvas pane's width in pixels
• H - The canvas pane's height in pixels

These values update automatically when you make any changes by dragging resize corners or handles.

ScrollBars

The Horizontal Scrollbar setting controls the appearance of a horizontal scrollbar across the bottom of the canvas pane, and the Vertical Scrollbar setting controls the appearance of a vertical scrollbar along the right edge of the canvas pane.

• Not Present - Turns off the scrollbar
• Present - Turns on the scrollbar

Once a scrollbar is added to the canvas pane, it allows the canvas pane to display an image (or canvas) larger than the canvas pane.

Drawing Model

If you want to assign a repaint handler to the canvas pane using connections, you must select the drawing model here. The model you choose should be supported by the toolkit postprocessor that you intend to use:

• GXV - Choose any of the three available drawing models.
• GOLIT - Choose XWindows only.

Initial State

There are two possible initial states for a canvas pane when its parent window first appears.

• Visible - The canvas pane appears when its parent window first appears.
• Invisible - The canvas pane is invisible when its parent window first appears.

Default Drop Site

Default Drop Site is a check box setting. Check Default Drop Site if you want the canvas pane to be the default drop site if a file or data is dropped on your application's icon. The drop is then forwarded to this drop site. You can have only one default drop site for your application. It must reside within the application's main base window.

Default Drop Site is enabled only if you have designated the canvas as a legal drop site. To do this, you must define a connection with the canvas pane as both source and target. Choose DroppedUpon from the When menu and CallFunction from the Action menu. The function whose name you supply will be called when a file or data is dropped on the canvas pane. See "Handling Events Using Connections" on page 81 for details.

Menu

Press MENU on the Menu button to display the New... and Names items. Names has an attached submenu. Choose New... to open the Menu Editor Window and create a new menu. To attach an existing menu to the canvas pane, choose the menu's name from the Names submenu, or enter the name on the line to the right of the Menu button.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the canvas pane.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the canvas pane.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the canvas pane.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the canvas pane and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Term Panes

A term pane is a region of a window where the program presents a UNIX shell to the user. It displays the workstation's prompt where the user can enter UNIX commands and work directly with the operating system. As the text of the user's session with the shell grows in length, it scrolls up and off the top edge of the term pane.

Editing the Properties of a Term Pane

To edit the properties of a UI term pane, select it and open its property window, shown in Figure 4-5. To do this, double-click SELECT on the term pane. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-5

Term Panes Scrolling List

The scrolling list at the top of the property windows lists each of the term panes in the current interface. To set the properties of a term pane, click SELECT on the pane's name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected term pane.

Object Name

Object Name establishes the name that Devguide gives the term pane in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the term pane.

Rectangle

The Rectangle entry contains four text fields that are used to describe a term pane.

• X - The distance in pixels of the upper-left corner of the term pane from the left edge of the parent (containing) window
• Y - The distance in pixels of the upper-left corner of the term pane from the top of the parent (containing) window
• W - The term pane's width in pixels
• H - The term pane's height in pixels

These values update automatically when you make any changes by dragging resize corners or handles.

Show Border

The Show Border setting controls the border that appears around a term pane.

• Yes - Turns on the border around the term pane
• No - Turns off the border

If you turn off the border, it won't disappear while you're in Build mode, but it will disappear when you enter Test mode.

Initial State

There are two possible initial states for a term pane when its parent window first appears.

• Visible - The term pane appears when its parent window first appears.
• Invisible - The term pane is invisible when its parent window first appears.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the term pane.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the term pane.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the term pane.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the term pane and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Text Panes

A text pane is a region of a window where the program displays text and where the user can edit text and enter new text. Each text pane has a boundary surrounding it. Because the text pane often contains more text than it can display at once, it has a vertical scrollbar on its right side that the user can use to scroll up and down through the text.

Editing the Properties of a Text Pane

To edit the properties of a UI text pane, select it and open its property window, shown in Figure 4-6. To do this, double-click SELECT on the text pane. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-6

Text Panes Scrolling List

The scrolling list at the top of the property windows lists each of the text panes in the current interface. To set the properties of a text pane, click SELECT on the pane's name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected text pane.

Object Name

Object Name establishes the name that Devguide gives the text pane in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the text pane.

Rectangle

The Rectangle entry contains four text fields that are used to describe a text pane.

• X - The distance in pixels of the upper-left corner of the text pane from the left edge of the parent (containing) window
• Y - The distance in pixels of the upper-left corner of the text pane from the top of the parent (containing) window
• W - The text pane's width in pixels
• H - The text pane's height in pixels

These values update automatically when you make any changes by dragging resize corners or handles.

Show Border

The Show Border setting controls the border that appears around a text pane.

• Yes - Turns on the border around the text pane
• No - Turns off the border

If you turn off the border, it won't disappear while you're in Build mode, but it will disappear when you enter Test mode.

Operation

The Operation setting determines whether text panes can accept input from the user, in addition to displaying text and numeric values.

• Read-write - Allows the user to alter text presented in the text pane
• Read-only - Locks the text so the user can't change it

Initial State

There are two possible initial states for a text pane when its parent window first appears.

• Visible - The text pane appears when its parent window first appears.
• Invisible - The text pane is invisible when its parent window first appears.

Foreground

Press MENU on the Foreground menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Foreground sets the foreground color of the text pane.

Background

Press MENU on the Background menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Background sets the background color of the text pane.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the text pane.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the text pane and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Buttons

A button is a control within a control area that initiates an action or presents an attached menu when the user selects the button. When the button has an attached menu, it's called a menu button.

Editing the Properties of a Button

To edit the properties of a button, double-click SELECT on it to open its property window, shown in Figure 4-7. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-7

Buttons Scrolling List

The scrolling list at the top of the property windows lists each of the buttons in the current interface. To set the properties of a button, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected button.

Object Name

Object Name establishes the name that Devguide gives the button in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the button.

Label

Contains the label (or glyph) that appears in the button. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the button is labeled with text or with a glyph.

• Text - Inserts the text entered in the Label text field as the button label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the button label

Location

The Location line contains two text fields:

• X - The distance in pixels of the upper-left corner of the button from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the button from the top of the control area

Type

The Type setting controls the appearance of the button when you have an attached menu.

• Full Sized - The button appears as a standard button with a button label within the button boundaries.
• Abbreviated Menu - The button appears as a small down-pointing arrow with the current menu choice appearing next to it.

Button Width Is

The Button Width Is setting sets the width of the button.

• Label Width - The button width changes to fit the length of the text in the button's label.
• Fixed - The button width remains fixed regardless of the button label.

The text field on the right side of the Button Width Is setting determines the length in pixels of the fixed width button.

Initial State

There are three possible initial states for a button when its parent control area first appears.

• Active - The button appears and is active when its parent control area first appears.
• Inactive - The button appears, but is inactive when its parent control area first appears.
• Invisible - The button is invisible when its parent control area first appears.

Menu

Press MENU on the Menu button to display the New... and Names items. Names has an attached submenu. Choose New... to open the Menu Editor Window and create a new menu. To attach an existing menu to the button, choose the menu's name from the Names submenu, or enter the name on the line to the right of the Menu button.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the button's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the button.

---

Note - Help text disappears if the foreground and background colors are set to any color close to the default color. This is a general color problem due to the fact that color is inherited from the base window. To avoid this problem, don't set the color.

---

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the button and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Messages

A message is a control that presents a message to the user in read-only text or as a glyph that the user can't alter. You can use messages to add text and images throughout a control area.

Editing the Properties of a Message

To edit the properties of a UI message, you double-click SELECT on it to open its property window, shown in Figure 4-8. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-8

Messages Scrolling List

The scrolling list at the top of the property windows lists each of the messages in the current interface. To set the properties of a message, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected message.

Object Name

Object Name establishes the name that Devguide gives the message in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the message.

Label

Contains the label (or glyph) that appears in the message. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the message is labeled with text or with a glyph.

• Text - Inserts the text entered in the Label text field as the message label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the message label

Label Font

The Label Font setting controls the appearance of the text label of the message UI element.

• Bold - The text appears in boldface.
• Normal - The text appears unemphasized.

Location

The Location line contains two text fields:

• X - The distance in pixels of the upper-left corner of the message from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the message from the top of the control area

Initial State

There are three possible initial states for a message when its parent control area first appears.

• Active - The message appears and is active when its parent control area first appears.
• Inactive - The message appears, but is inactive when its parent control area first appears.

• Invisible - The message is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the message's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the message.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the message and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first

selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Settings

A setting is a control that offers on or off choices for a collection of related options. There are four types of settings: exclusive, nonexclusive, check boxes, and stacks. Stacks, exclusive settings, and check boxes have glyphs in Devguide's palette. You can use any setting glyph to create any one of these types of settings.

Editing the Properties of a Setting

To edit the properties of a UI setting, select it and open its property window, shown in Figure 4-9. To do this, double-click SELECT on the setting. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-9

Settings Scrolling List

The scrolling list at the top of the property windows lists each of the settings in the current interface. To set the properties of a setting, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected setting.

Object Name

Object Name establishes the name that Devguide gives the setting in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the setting.

Label

Contains the label (or glyph) that appears in the setting. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the setting is labeled with text or with a glyph, and determines the label's location.

• Text - Inserts the text entered in the Label text field as the setting label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the setting label
• Left - Places the label to the left of the setting
• Above - Places the label above the setting

Location

The Location line contains two text fields:

• X - The distance in pixels of the upper-left corner of the setting from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the setting from the top of the control area

Type

Offers an abbreviated menu button that allows you to choose the type of a setting.

• Exclusive - Allows the user to turn on only one of its options at a time. When the user chooses an option, it turns on, and all other options in the setting automatically turn off.
• Nonexclusive - Allows the user to turn on each option within the setting or menu without affecting any of the other options. When the user chooses an option, it turns on if it is off, and off if it is on. (It toggles.) All other options in the setting are unaffected by the selection. Many options can be on at the same time.
• Check Box - Works the same way a nonexclusive setting works. It differs in appearance: each option label appears to the right of a check box. When the option is turned on, a check appears in the check box. When turned off, the check box is empty.
• Stack - Works much the same way an exclusive setting works. It differs in that it doesn't show all the options at one time, but only shows the label, an abbreviated button, and the option that is currently turned on displayed to the right of the button. To see all the options, the user clicks on the button with MENU to display the options in a vertical list and choose one of them. This is the same as an abbreviated menu button.

Choice

Exclusive settings allow you the flexibility of requiring or not requiring the user to make a choice.

• Required - The user must select one of the choices available.
• Not Required - The user needn't select any choice available.

Rows/Columns

Arranges the setting items in row or column format.

• Rows - Displays the items in a series of rows
• Columns - Displays the items in a series of columns

Enter the number of rows or columns you want in the text field to the right of the setting.

Initial State

There are three possible initial states for a setting when its parent control area first appears.

• Active - The setting appears and is active when its parent control area first appears.
• Inactive - The setting appears, but is inactive when its parent control area first appears.
• Invisible - The setting is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the setting's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the setting.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the setting and other existing UI elements using the Connections Manager.

The Items Scrolling List

The scrolling list below the Connections... button is the Items scrolling list; it contains the items available in the setting. When you first create a setting, there are two items in the list labeled "Item." To change an item, select it. A box appears around it to show that it's selected, and its label appears in the Label

text field just below the scrolling list. To change the item's label, select the Label text field and then use the keyboard to change its contents. Click on the Apply button or any other item in the scrolling list to apply your label change.

Insert Button

The Insert button below the Items scrolling list allows you to insert a new item at any location in the scrolling list. Select one of the items to insert a new item where you want it:

• Before - Inserts a new item before the selected item
• After - Inserts a new item after the selected item
• Top - Inserts a new item at the top of the scrolling list
• Bottom - Inserts a new item at the bottom of the scrolling list

Edit Button

The Edit button below the Items scrolling list offers options that cut, copy, and paste items within the scrolling list. Use these functions to move items from one location to another:

• Cut - Removes the selected item from the scrolling list and places it in the item clipboard.
• Copy - Puts a copy of the selected item in the item clipboard.
• Paste - Puts the contents of the clipboard in the scrolling list. The four choices in the submenu are Before, After, Top, and Bottom, which insert the clipboard contents in the same locations as the corresponding items in the Insert button menu.

Label

Contains the label (or glyph) that appears as the setting item's label. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the setting item is labeled with text or with a glyph.

• Text - Inserts the text entered in the Label text field as the item's label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the item's label

Item Is

The Item Is setting determines whether or not an item is selected when the setting first appears. For stacks, Item Is also determines whether or not a setting item is the default item. The current selection (initially the default) appears to the right of the stack's abbreviated menu button.

• Not Selected - The item is initially not selected.
• Selected - The item is initially selected.
• Normal (stacks) - The item is a normal item (not the default).
• Default (stacks) - The item is the default.

Only one item in each stack can be a default item. When you set an item as the default, any other item which had been the default becomes a normal item.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the color of the setting item you create.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the setting item and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Text Fields

A text field is a control that requests a string of text from the user or presents a string of text for the user to edit. Text fields are typically used to request values or file names. A numeric text field is a special type of text field that accepts only numeric values. A multiline text field allows the user to display multiple lines of text in a control area. Alphanumeric and numeric text fields have glyphs on Devguide's palette. You can use any text field glyph to create any one of the three types of text fields.

Editing the Properties of a Text Field

To edit the properties of a UI text field, select it and open its property window, shown in Figure 4-10. To do this, double-click SELECT on the text field. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-10

Text Fields Scrolling List

The scrolling list at the top of the property windows lists each of the text fields in the current interface. To set the properties of a text field, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected text field.

Object Name

Object Name establishes the name that Devguide gives the text field in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the text field.

Label

Contains the label (or glyph) that appears in the text field. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the text field is labeled with text or with a glyph, and determines the label's location.

• Text - Inserts the text entered in the Label field as the text field label
• Glyph Filename - Inserts the glyph described in the file specified in the Label field as the text field label
• Left - Places the label to the left of the text field
• Above - Places the label above the text field

Location

The Location line contains two fields:

• X - The distance in pixels of the upper-left corner of the text field from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the text field from the top of the control area

Field Type

A text field can present and accept three different types of information:

• Alphanumeric - The standard text field
• Multiline - Multiple lines of text
• Numeric - Numbers only

Rows

Set Rows to the number of rows you want to be visible in the multiline text field.

Range

If you use the Field Type setting to create a numeric text field, the Range line sets the upper and lower limits for the numeric values the text field handles.

• Min - Sets the minimum numeric value available
• Max - Sets the maximum numeric value available

Field Length

The Field Length field sets the displayed length in characters of the selected UI text field.

Stored Length

The Stored Length field sets the maximum length in characters of the UI text field storage capacity. A scrollbar appears in a multiline text field whenever the text you enter exceeds what can be displayed within the text field's borders.

Underline

Underline determines whether or not the text appearing in the text field is underlined.

• Present - The text is underlined.
• Not Present - The text is not underlined.

Operation

The Operation setting determines whether text fields can accept new input from the user in addition to displaying text and numeric values.

• Read-write - Accept input from the user.
• Read-only - Refuse input from the user.

Initial Value

The Initial Value field allows you to assign text strings, numeric values, or multiple lines of text to your text field. This value appears in the text field when it is initially displayed. A scrolling button allows you to enter as much text as you want for a multiline text field.

Initial State

There are three possible initial states for a text field when its parent control area first appears.

• Active - The text field appears and is active when its parent control area first appears.
• Inactive - The text field appears, but is inactive when its parent control area first appears.
• Invisible - The text field is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the text field's color.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the text field and other existing UI elements using the Connections Manager.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the text field.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Sliders

A slider is a control within a control area that sets a single value from a continuous range of values. To set the value, the user drags the slider back and forth.

Editing the Properties of a Slider

To edit the properties of a slider, select it and open its property window, shown in Figure 4-11. To do this, double-click SELECT on the slider. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-11

Sliders Scrolling List

The scrolling list at the top of the property windows lists each of the sliders in the current interface. To set the properties of a slider, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected slider.

Object Name

Object Name establishes the name that Devguide gives the slider in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the slider.

Label

Contains the label (or glyph) that appears in the slider. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the slider is labeled with text or with a glyph, and determines the label's location.

• Text - Inserts the text entered in the Label text field as the slider label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the slider label
• Left - Places the label to the left of the slider
• Above - Places the label above the slider

Location

The Location line contains three fields:

• X - The distance in pixels of the upper-left corner of the slider from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the slider from the top of the control area

• Width - The width of the slider in pixels

Orientation

The Orientation setting controls the orientation of the slider.

• Horizontal - The slider runs left and right.
• Vertical - The slider runs up and down.

Value

The Value setting controls the presence of the slider's value at the left or top end of the slider.

• Present - The current value appears.
• Not Present - The current value doesn't appear.

Range

The Range line controls the range of the slider.

• Show - The range appears, with the minimum value available displayed on the left or low end and the maximum value available displayed on the right or high end.
• Hide - The minimum and maximum values don't appear.
• Min - You set the minimum numeric value available here.
• Max - You set the maximum numeric value available here.

Value String

You can supply text strings to appear at either end of the slider, instead of the minimum and maximum values you have set.

• Min - Text string to represent the minimum value you have set (in Range)
• Max - Text string to represent the maximum value you have set (in Range)

End Boxes

The End Boxes setting controls the presence of end boxes (small boxes at each end of the slider).

• Present - Adds end boxes to the slider
• Not Present - Removes end boxes from the slider

Ticks

The Ticks field controls both the presence and number of tick marks along the slider. If you enter a value of 0, no tick marks are displayed. If you set a value of 2 or higher, that many tick marks appear along the slider.

Tick String

You can supply text strings that appear under the first and last tick marks if ticks are displayed.

• Min - Text string that appears under the first tick mark
• Max - Text string that appears under the last tick mark

Initial Value

The Initial Value text field allows you to set the slider to a number in the Min/Max range you specify in Range. The slider is set and the number appears to the left of the slider when the slider initially appears.

Initial State

There are three possible initial states for a slider when its parent control area first appears.

• Active - The slider appears and is active when its parent control area first appears.
• Inactive - The slider appears, but is inactive when its parent control area first appears.
• Invisible - The slider is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the slider's color.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the slider and other existing UI elements using the Connections Manager.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the slider.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Gauges

A gauge is a read-only slider that presents a value to the user that the user can't change.

Editing the Properties of a Gauge

To edit the properties of a gauge, select it and open its property window, shown in Figure 4-12. To do this, double-click SELECT on the gauge. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-12

Gauges Scrolling List

The scrolling list at the top of the property windows lists each of the gauges in the current interface. To set the properties of a gauge, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected gauge.

Object Name

Object Name establishes the name that Devguide gives the gauge in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the gauge.

Label

Contains the label (or glyph) that appears in the gauge. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the gauge is labeled with text or with a glyph, and determines the label's location.

• Text - Inserts the text entered in the Label text field as the gauge label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the gauge label
• Left - Places the label to the left of the gauge
• Above - Places the label above the gauge

Location

The Location line contains three fields:

• X - The distance in pixels of the upper-left corner of the gauge from the left edge of the control area
• Y - The distance in pixels of the upper-left corner of the gauge from the top of the control area
• Width - The width of the gauge in pixels

Orientation

The Orientation setting controls the orientation of the gauge.

• Horizontal - The gauge runs left and right.
• Vertical - The gauge runs up and down.

Range

The Range line controls the range of the gauge.

• Show - The range appears, with the minimum value available displayed on the left or low end and the maximum value available displayed on the right or high end.
• Hide - The minimum and maximum values don't appear.
• Min - You set the minimum numeric value available here.
• Max - You set the maximum numeric value available here.

Ticks

The Ticks field controls both the presence and number of tick marks along the gauge. If you enter a value of 0, no tick marks are displayed. If you set a value of 2 or higher, that many tick marks appear along the gauge.

Tick String

You can supply text strings that appear under the first and last tick marks.

• Min - Text string that appears under the first tick mark
• Max - Text string that appears under the last tick mark

Initial Value

The Initial Value text field allows you to set the gauge to a number in the Min/Max range you specify in Range. The gauge is set when it initially appears.

Initial State

There are three possible initial states for a gauge when its parent control area first appears.

• Active - The gauge appears and is active when its parent control area first appears.

• Inactive - The gauge appears, but is inactive when its parent control area first appears.
• Invisible - The gauge is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the gauge's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the gauge.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the gauge and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Scrolling Lists

A scrolling list presents a vertical list of text items and glyphs through which the user can scroll and select items using the pointer. A scrolling list is typically used whenever a set of choices varies in number from one instance to the next or when there are too many choices to present comfortably in a limited space.

Editing the Properties of a Scrolling List

To edit the properties of a UI scrolling list, select it and open its property window, shown in Figure 4-13. To do this, double-click SELECT on the scrolling list. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-13

Lists Scrolling List

The scrolling list at the top of the property windows lists each of the UI scrolling lists in the current interface. To set the properties of a UI scrolling lists, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected UI scrolling list.

Object Name

Object Name establishes the name that Devguide gives the scrolling list in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the scrolling list.

Label

Contains the label (or glyph) that appears in the scrolling list. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the scrolling list is labeled with text or with a glyph, and determines the label's location.

• Text - Inserts the text entered in the Label text field as the scrolling list label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the scrolling list label
• Left - Places the label to the left of the scrolling list
• Above - Places the label above the scrolling list

Location

The Location line contains three fields:

• X - The distance in pixels of the upper-left corner of the scrolling list from the left edge of the control area

• Y - The distance in pixels of the upper-left corner of the scrolling list from the top of the control area
• Width - The width of the scrolling list in pixels

Rows

Set Rows to the number of rows you want visible in the scrolling list.

Operation

The Operation setting determines whether the scrolling list can accept new input from the user in addition to displaying text and numeric values.

• Read-write - Accept input from the user.
• Read-only - Refuse input from the user.

Choice

A scrolling list can require that one of its items is always chosen, or it can permit the user to make no selection.

• Not Required - Allows the user the option of choosing no item
• Required - Requires one item to be chosen

Choices

A scrolling list can allow the user to choose only one of its items at a time (exclusive) or as many of its items as the user cares to choose (nonexclusive).

• Exclusive - Permits a single choice from the scrolling list
• Nonexclusive - Permits multiple choices from the scrolling list

Initial State

There are three possible initial states for a scrolling list when its parent control area first appears.

• Active - The scrolling list appears and is active when its parent control area first appears.

• Inactive - The scrolling list appears, but is inactive when its parent control area first appears.
• Invisible - The scrolling list is invisible when its parent control area first appears.

Default Drop Site

Default Drop Site is a check box setting. Check Default Drop Site if you want the scrolling list to be the default drop site if a file or data is dropped on your application's icon. The drop is then forwarded to this drop site. You can have only one default drop site for your application. It must reside within the application's main base window.

Default Drop Site is enabled only if you have designated the scrolling list as a legal drop site. To do this, you must define a connection with the scrolling list as both source and target. Choose DroppedUpon from the When menu and CallFunction from the Action menu. The function whose name you supply will be called when a file or data is dropped on the scrolling list. See "Handling Events Using Connections" on page 81 for details.

Menu

Press MENU on the Menu button to display the New... and Names items. Names has an attached submenu. Choose New... to open the Menu Editor Window and create a new menu. To attach an existing menu to the scrolling list, choose the menu's name from the Names submenu, or enter the name on the line to the right of the Menu button.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Colors sets the scrolling list's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the scrolling list.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the scrolling list and other existing UI elements using the Connections Manager.

Items Scrolling List

The scrolling list below the Connections... button contains the items available in the scrolling list you create. When you first create a scrolling list, the Items scrolling list is empty. You add items to the scrolling list as explained below. To change an item, select it. A box appears around it to show that it's selected, and its label appears in the Label text field just below the scrolling list. To change the item's label, select the Label text field and then use the keyboard to change its contents. Click on the Apply button or any other item in the scrolling list to apply your label change.

Insert Button

The Insert button below the Items scrolling list allows you to insert a new item at different locations in the scrolling list. The options to insert a new item where you want it are:

• Before - Inserts a new item before the selected item
• After - Inserts a new item after the selected item
• Top - Inserts a new item at the top of the scrolling list
• Bottom - Inserts a new item at the bottom of the scrolling list

Edit Button

The Edit button below the Items scrolling list offers cut, copy, and paste choices within the scrolling list. Use these to move items from one location to another:

• Cut - Removes the selected item from the scrolling list and places it in the clipboard.
• Copy - Puts a copy of the selected item in the clipboard.

• Paste - Puts the contents of the clipboard in the scrolling list. The four items in its submenu offer Before, After, Top, and Bottom, which insert the clipboard contents in the same locations as the corresponding items in the Insert button menu.

Label

Contains the text label that appears as the item's label.

Glyph

An item can have a glyph displayed to the left of its label in the scrolling list. Enter the glyph file name on this line if you want the item to have a glyph.

Item Is

The Item Is setting determines whether or not an item is selected when the scrolling list first appears.

• Not Selected - The item is initially not selected.
• Selected - The item is initially selected.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the scrolling list invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.

Drop Targets

A drag and drop target is a region in a control area where drag and drop operations can be performed.

Editing the Properties of a Drop Target

To edit the properties of a UI drag and drop target, select it and open its property window, shown in Figure 4-14. To do this, double-click SELECT on the drag and drop target. See "Opening UI Element Property Windows" on page 60 for other methods of opening property windows.

Figure 4-14

Drop Targets Scrolling List

The scrolling list at the top of the property windows lists each of the UI drag and drop targets in the current interface. To set the properties of a UI drag and drop targets, click SELECT on its name. The name is boxed to show that it's selected, and the controls in the rest of the property window change to show the current settings of the selected UI drag and drop target.

Object Name

Object Name establishes the name that Devguide gives the drag and drop target in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the drag and drop target.

Label

Contains the label (or glyph) that appears to the left of the drag and drop target. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the drag and drop target is labeled with text or with a glyph.

• Text - Inserts the text entered in the Label text field as the drag and drop target label
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the drag and drop target label

Location

The Location entry contains two text fields that are used to describe a drag and drop target.

• X - The distance in pixels of the upper-left corner of the drag and drop target from the left edge of the parent (containing) window
• Y - The distance in pixels of the upper-left corner of the drag and drop target from the top of the parent (containing) window

Default Drop Site

Default Drop Site is a check box setting. Check Default Drop Site if you want the drag and drop target to be the default drop site if a file or data is dropped on your application's icon. The drop is then forwarded to the drag and drop target. You can have only one default drop site for your application. It must reside within the application's main base window.

Drag Type

The Drag Type setting determines whether data can be dragged from the drag and drop target.

• Not Draggable - You can only drop onto the drag and drop target.
• Draggable - You can drag from and drop onto the drag and drop target.

Normal Glyph

You can specify a glyph file name in the Normal Glyph text field. The glyph described in the file is inserted as the drag and drop target's default glyph, and appears when the application is started. If you do not specify a file name, the drag and drop target's normal glyph looks like the UI element glyph on Devguide's palette. Normal glyph is disabled if you select Not Draggable for the drag and drop target's Drag Type.

Busy Glyph

You can specify a glyph file name in the Busy Glyph text field. The glyph described in the file is visible whenever your application is processing a drop operation. If you do not specify a filename, Devguide provides a default busy glyph.

The busy glyph is displayed when you drag data from a drag and drop target, if you select Draggable for the Drag Type. It is also displayed during a preview, if the drag and drop target is a valid drop site.

Drag Cursor

You can specify a glyph file name in the Drag Cursor text field. This file describes the cursor that is displayed when you drag data from the drag and drop target. If you do not specify a filename, a default drag cursor glyph is provided. Drag Cursor is disabled if you select Not Draggable for the drag and drop target's Drag Type.

Hot Spot

The Hot Spot entry can contains two text fields that are used to describe the drag cursor's hot spot. Hot Spot is disabled if you select Not Draggable for the drag and drop target's Drag Type, or if you have not supplied a file name in the Drag Cursor text field.

• X - The distance in pixels of the upper-left corner of the hot spot from the left edge of the box containing the drag cursor
• Y - The distance in pixels of the upper-left corner of the hot spot from the top of the box containing the drag cursor

Accept Cursor

You can specify a glyph file name in the Accept Cursor text field. The glyph described in the file is used as the accept cursor. This cursor is displayed to identify a legal drop site. The drag and drop target's drag cursor changes into the accept cursor when its hot spot is on top of a legal drop site. Accept Cursor is disabled if you select Not Draggable for the drag and drop target's Drag Type.

Hot Spot

The Hot Spot entry can contains two text fields that are used to describe the accept cursor's hot spot. Hot Spot is disabled if you select Not Draggable for the drag and drop target's Drag Type, or if you have not supplied a file name in the Accept Cursor text field.

• X - The distance in pixels of the upper-left corner of the hot spot from the left edge of the box containing the accept cursor
• Y - The distance in pixels of the upper-left corner of the hot spot from the top of the box containing the accept cursor

Initial State

There are three possible initial states for a drag and drop target when its parent control area first appears.

• Active - The drag and drop target appears and is active when its parent control area first appears.
• Inactive - The drag and drop target appears, but is inactive when its parent control area first appears.
• Invisible - The drag and drop target is invisible when its parent control area first appears.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color Chooser. Color sets the drag and drop target's color.

Help Text...

The Help Text... button opens the Help Editor window, where you can add or edit help text for the drag and drop target.

Connections...

When you click SELECT on Connections..., the Connections Manager window appears. You can establish connections between the drag and drop target and other existing UI elements using the Connections Manager.

Apply

Clicking SELECT on Apply makes your changes permanent. You cannot undo these changes with an undo command. If you want to change an element's properties after you SELECT Apply, enter new property field values and SELECT Apply again. Dismissing the property window without choosing Apply does not apply changes.

---

Note - When you have been editing one UI element, clicking on another element in the drag and drop target invokes an implicit Apply on the first element, saving all your changes. If you wish to go to another element without saving your changes, you must first click on Reset.

---

Reset

Clicking SELECT on Reset returns all the controls in the property window to their original settings or to the settings as they were when you last chose the Apply button. (The original settings are the ones that appeared when you first selected a UI element from the scrolling list, or the settings that appeared when you first opened the property window.) Reset only resets the properties; it does not undo them after an apply.