skip to main content
OpenEdge Development: AppBuilder
Organizer Objects : SmartWindows
 
SmartWindows
SmartWindows are general‑purpose, outer‑level organizer objects. They have ADM Smart technology embedded in them, and can fully integrate other SmartObjects such as SmartDataObjects, SmartToolbars, and so forth. SmartWindows are members of the SmartContainer class. Unlike the other SmartContainer objects, a SmartWindow can serve as your application’s main window or as one of the windows in a multi‑window design.
Note that a SmartWindow comes fitted with a frame that covers the client area of the window. The frame should automatically resize as you resize the SmartWindow. You can also resize it separately, if you choose. You might wish to do that in order to have room for additional frames. Besides providing the required context for widget placement, frames also group widgets for traversal using the TAB key, and you might wish to define more than one such group. Note that, rather than resizing the default frame, you could instead add a new frame for each separate traversal group, overlaying the default frame.
SmartWindows are file‑level (external procedure) objects. Unlike the objects embedded in ABL itself, objects defined by external procedures typically are complex. Such objects have a set of properties associated with their nature as a subprogram module, and additional sets—if they have a visible run‑time representation—associated with whatever widgets they put up as their user interface. The sections below discuss these different properties and their meanings.
Configuring SmartWindow visual properties
Configuring the visual properties for your new SmartWindow can be simple or complex, depending on how well the default settings suit your purpose.
Whenever you create a SmartWindows object using AppBuilder, you actually create two visible elements: a window and a frame. The frame completely covers the client area of the window, and resizes itself when you resize the window. Because of that, it may not be at all obvious to you at first that you are dealing with two different elements or how to open the Properties dialog box for the underlying window rather than for the frame that covers it.
Both the window and frame elements have properties you may wish to set. This section describes the properties that apply to the window part. See the “Configuring SmartFrame visual properties” section for a discussion of properties unique to frames.
Opening the property sheet for the underlying window
Perhaps the most common way to open the property sheet for any object is to double‑click on its client area, if you have your preferences set the way. But the overlying frame will prevent you from doing that here: double‑clicking will open the property sheet for the frame, not the window.
To open the Properties dialog box for the window part of the SmartWindow object, use one of the following methods:
*While holding down the CTRL key, click in the client area of the SmartWindow until you see that you have the window selected (its identifier will display in the Object field of AppBuilder’s main window). Then choose ToolsProperty Sheet.
Although this method is the preferred, you may find it requires several clicks if the window is not empty.
*Expose some of the underlying window. Then double‑click on the area you exposed.
Caution: You should not leave bare window surface exposed unnecessarily, since there is a slight possibility that you might then unintentionally place an object partly outside the frame, causing it to disappear.
To expose some of the underlying window:
1. Select the frame part of the SmartWindow by clicking in the client area (the area below the title bar). A border with handles will appear, as shown:
2. Drag the bottom‑center handle upward a bit. This exposes the surface of the underlying window widget, though there might be little or no visible difference.
Once you have the window selected, opening the property sheet will cause the dialog box shown in Figure 19 to appear.
Figure 19: Window property sheet
Minimal configuration changes
Although you can choose to accept many default settings, you should at least ensure that each SmartWindow you create is uniquely identifiable. To individualize a SmartWindow, make the following changes:
*Change the generic instance identifier to one that more closely describes the window instance you are creating. The instance identifier is the token that will appear in the source code, and is the default value for the filename. Note that OpenEdge identifiers for window objects are conventionally prefixed with a w.
*Change the generic title bar text to a string that identifies the particular window, or the application if the window you are creating is its main window.
*Click each of the icon image buttons and identify the icon bitmap (.ico) files for the large (32x32) and small (16x16) icons that will be used to represent the window.
Miscellaneous properties (other settings)
There are a number of changes to a window’s appearance or behavior that you can make, if the default settings do not suit your purposes. They are listed here:
*3D — Normally set. Clearing this box changes the color of the window’s client area, but has no other obvious effect.
*Control‑Box — Normally set. Clearing this box clears and disables the Max‑Button and Min‑Button check boxes. The run‑time effect is to remove all three buttons from the right end of the window’s title bar and the small icon from the left end. Only the title string remains.
*Drop‑Target — Normally cleared. Setting this box causes the window to generate an event when some object is dragged and dropped onto it. You can write code to intercept and respond to such events under program control.
*Explicit Position — Normally cleared. Setting this box enables the Column and Row settings in the Geometry section, and initializes them to the current location of the upper‑left corner of this window. You can then freely reposition the window during design time, and the window will start up in the location you choose rather than in some location determined by the operating system.
*Hidden — Normally cleared. Setting this box prevents this window from displaying itself in response to implicit requests. Explicit code must be used to display a HIDDEN window. If initializing this SmartWindow will take a noticeable amount of time, keeping the window hidden meanwhile might be less worrisome to your customer, as long as you display a progress indicator.
*Keep-Frame-Z‑Order — Normally set by AppBuilder when generating code. Prevents nested frames from inappropriately changing their layering in response to getting the input focus.
*Max-Button, Min-Button — Normally set. Clearing these boxes eliminates the buttons that appear at the right end of the title bar. Those buttons allow the user to make the window go to a full‑screen or iconic state, respectively.
*Message-Area — Normally cleared. Setting this box adds an area for messages at the bottom of the window, but above any Status Area. Character windows always have a Message Area.
*Resize — Normally cleared. Setting this box allows the user to resize the window by dragging its edges. Widgets in the client area do not respond automatically to this resizing in any way.
*Scroll-Bars — Normally cleared. Setting this box allows scroll bars to be automatically activated as needed.
Setting the Scroll Bars option gives meaning to the Virtual Width/Height values shown in the Geometry section. Scroll bars exist to move different portions of some notional space into and out of view as desired. The size of the area currently in view is reflected in the Width and Height numbers, shown in character units in the main property sheet and pixel units in the Advanced Properties dialog box. The total size of the logical area, both visible and scrolled‑off, is shown by the Virtual numbers. Those dimensions are referred to as Virtual rather than Total because they could conceivably represent a much larger area than could be displayed whole by any physical device. Unless the window can be scrolled, however, the total and visible areas are effectively identical, making the Virtual numbers meaningless for practical purposes.
*Sensitive — Normally set. Clearing this box causes the window to decline the input focus when offered.
*Show-in-Taskbar — Normally set. Clearing this box causes the window to iconize to a position above the taskbar rather than within the taskbar itself.
*Small-Title — Normally cleared. Setting this box has the same effect as clearing Control Box, plus it reduces the height of the title bar to the minimum needed for the title.
*Status-Area — Normally cleared. Setting this box adds a status area at the bottom of the window.
*Suppress Window — Normally cleared. Setting this box effectively removes the window widget, leaving only the frame. Frames are displayed by default in the current window, which might be a scratch window created for the purpose.
*View — Normally set. This is useful only when the frame is HIDDEN.
Menus
Unlike SmartDialogs and SmartFrames, a SmartWindow can have a menu bar and pull‑down menus. It can also have a pop‑up menu. You create both types of menu using the same editor and the same procedure.
Note: You cannot use this menu if you plan to place a SmartToolbar, even if you only intend to use the toolbar element of that object. The built-in menu and the SmartToolbar are incompatible. See the description of the SmartToolbar object in OpenEdge Development: ADM and SmartObjects.
The procedure for creating a pop‑up menu is identical to creating a menu bar and pull-down menus, apart from the button you choose at the start.
To create a menu bar and pull-down menus:
1. Click Menu Bar in the property sheet. The editor dialog box appears:
2. Change the default identifier for the menu object to reflect your naming conventions, if desired.
3. Enter the label for the first menu item. A corresponding identifier will immediately be generated in the Object field. You can modify that identifier, if desired, using the following methods:
*You must precede one of the letters in each label with an ampersand (&) so the user can choose the menu item from the keyboard. The choice of letter must uniquely identify the menu item within its group (bar or pull‑down). If you have not determined where this item will reside, you can defer selecting a character until later.
*By convention, a menu item on a pull‑down ends in an ellipsis (...) if choosing it will open another level of pull‑down or invoke a dialog box. Example: Save As...
*If you wish to define string attributes for the label, enter them in the area to the right of the label. For further information, see the “String attributes” section.
4. Repeat Step 3 until you have entered all the items that will appear anywhere in the menu system you are creating.
5. Select each menu item that is to appear in a pull‑down rather than on the bar. Mark it by choosing the >> button. You will see a dash appear in front of the item. The >> button can be used more than once, and each use will prepend another dash. The number of dashes indicates the nesting level of the pull‑down on which the item will appear, defined as follows:
*No dashes means the item will be on the menu bar itself.
*One dash means the item will be on the main pull‑down menu.
*Two dashes means the item will be on a cascade/fly-out menu off the pull‑down.
*Three dashes means the item will be on a second level of cascade menu.
If you change your mind, remove unwanted dashes by choosing the << button.
6. Select each menu item and use the Up and Down buttons to move it into the correct position relative to the other items. The first item on a pull‑down menu should appear immediately below the item that causes the pull‑down to open. Example: in the figure shown in Step 1, the Cut item would be the first item in the Edit pull‑down.
If the item is a pull‑down item, and is to appear with a check mark in front of it whenever selected, check the Toggle‑box option.
7. Arrange pull‑down items into logical groups by inserting rule lines (Rule button) and nonselectable blank items (Skip button) as appropriate.
8. Select each item that will be frequently used and define an accelerator (shortcut) key for it. Click Key and, when the capture dialog appears, press the actual key or combination (such as CTRL+X for Cut) that is to become the shortcut.
Note: To create a shortcut for an item on the menu bar, you must first change it to a pull‑down item using the >> button. After you have defined the shortcut, move it back to the menu bar using the << button. The shortcut will remain defined.
9. Select each item that will not be active on startup and check the Disabled box. Save your work.
Context‑sensitive help
If you plan to provide context‑sensitive help, check the Context Help box and specify the full pathname of the relevant help file.
String attributes, window color, status area font
You can set several other characteristics of the window, if you choose:
*String attributes.
*Font used for text written to the Status Area, if any.
*Colors used for the window’s foreground and background. By default, MS‑Windows applications leave their window colors undefined so that the end user can set them as a preference item.
See the online help system for further information.
Advanced properties
Click Advanced to set additional properties. The Advanced Properties dialog box appears:
The advanced properties shown here are common to most objects. You can modify any that do not meet your needs:
*Private Data — Not used by AppBuilder. AppBuilder assigns the contents of this field to the window’s PRIVATE-DATA attribute. You can write code to read and operate on that value in any way that meets your needs.
*Generated Code Layout Unit — Determines whether AppBuilder uses character or pixel units when generating source code for this object.
*Custom Lists — Custom lists would be called macros in other languages such as C. They provide a convenient way to avoid typing a large number of identifiers when many objects are to be treated identically. For example, if you check the box for List 1, the identifier for this window is associated with List 1. Later, any time a reference to this procedure’s List 1 is encountered by the preprocessor, the identifier for this window—together with the identifiers for all other objects you associated with List 1 in this procedure—will be substituted in the source code in place of the reference. You can choose to include this window in up to six such macros.
You can also give the macros themselves more meaningful identifiers. See the “Custom lists naming” section for additional information.
*Geometry - Pixels — You can set the exact startup size and position for this window, in pixel units. Startup position is only meaningful when you set the Explicit Position box.
*Always-on-Top, Top-Only — You can set either of these options, but not both. Neither is set by default:
*Top Only prevents this window from being occluded by other windows belonging to this session.
*Always on Top prevents this window from being occluded by any other window, even those belonging to other applications.
*Sync With Master — Forces this layout to take on the attributes of the master layout. This button is disabled unless this layout is an alternate layout. For more information on alternate layouts, see Appendix B, “Multiple Layouts”.