BBjTopLevelWindow

Description

A BBjTopLevelWindow is an object that represents a TopLevelWindow control. A TopLevelWindow is the outermost form of window and can be displayed on screen by itself (without a parent). This window can contain child windows and controls.

The BBjTopLevelWindow extends from BBjWindow and implements all methods from BBjWindow and BBjControl.

Implemented Interfaces

MouseWheelEnabled

Creation

BBjAPI > BBjSysGui > BBjWindow > BBjTopLevelWindow

A BBjTopLevelWindow object is created through the following BBjSysGui methods:

Return Value Method
BBjTopLevelWindow addWindow(number x, number y, number width, number height, string title)
BBjTopLevelWindow addWindow(number x, number y, number width, number height, string title, string flags)
BBjTopLevelWindow addWindow(number x, number y, number width, number height, string title, string flags, string event_mask)
BBjTopLevelWindow addWindow(int context, number x, number y, number width, number height, string title)
BBjTopLevelWindow addWindow(int context, number x, number y, number width, number height, string title, string flags)
BBjTopLevelWindow createTopLevelWindow(int resHandle, int windowID)

Creation Flags

Flag Description
$00000001$

Resizable: Allows the window to be resized.

$00000002$ Close box: Includes a close box with the window.
$00000004$

Horizontal Scrollbar: Causes a horizontal scroll bar to appear when the window is resized to be smaller than its initial size and setTrack(0) is specified.

Note: Pair this with flag $80000000$ to set 'TRACK'(0).

$00000008$

Vertical Scrollbar: Causes a vertical scroll bar to appear when the window is resized to be smaller than its initial size and setTrack(0) is specified.

Note: Pair this with flag $80000000$ to set 'TRACK'(0).

$00000010$ Invisible: Sets the window to be initially invisible.
$00000020$ Disabled: Sets the window to be initially disabled.
$00000080$ Maximizable and Minimizable: Allows the window to be maximized or minimized.
$00000100$ Minimized: Sets the window to be initially minimized.
$00000800$ Menu Bar: Include menu bar. Creates a menu bar.
$00001000$ Maximized: Sets the window to be initially maximized.
$00002000$ Prevents the separator line between the menu and client area of a window from being drawn.
$00010000$ Keyboard Navigation: Activates keyboard navigation in the window. If this flag is specified, key pressed ("t") events for arrow keys and the tab key will not be reported.
$00020000$ Always On Top: Always positions the window on top of other windows.
$00040000$ Border: Creates a border around the dialog.
$00080000$ Dialog: Sets the window to behave as a dialog.
$00100000$

Automatic Layout: Automatically arranges all controls and child windows placed in the window to fit. In the DWC client, this flag causes the window to use dynamic flow layout, ignoring all absolute control sizes and positions.

Note:

When creating a child window through an ARC file in WindowBuilder, this flag is not currently exposed in the UI, and corresponds to the "GRAVITY" flag. To enable flow layout in the DWC, add a line with the keyword GRAVITY to the ARC source file in the section with the child window properties.

$00400000$ Custom Colors: Allows use of a custom color palette. This provides a more accurate display of colors in bitmapped images.
$00800000$ Enter as Tab: Sets the Enter key to behave as a Tab key.
$01000000$ No Title Bar: Creates the window without a title bar.
$02000000$ MDI Desktop Modal: In BBj 23.04 and higher, sets the window to be desktop modal within an MDI desktop. This flag is ignored if the window isn't on an MDI desktop.
$04000000$ SYSCOLOR Events: Sets the window to automatically manage SYSCOLOR events.
$08000000$ Unique Names: In BBj 8.00 and higher, causes the window to enforce unique control names. See BBjWindow::getControl.
$10000000$ All Mouse Events: In BBj 15.00 and higher, causes the window to report all mouse events for all controls.
$20000000$ All Keypress Events: In BBj 15.00 and higher, causes the window to report all keypress events for all controls.
$40000000$ MDI Group Modal: Sets the window to be group-modal within an MDI group.
$80000000$ TRACK(0): In BBj 17.00 and higher, creates the window with 'TRACK'(0) instead of the default 'TRACK'(1). Use this option to enable scrolling behavior in combination with flags $00000004$ (horizontal scrollbar) or $00000008$ (vertical scrollbar).

Methods of BBjTopLevelWindow

Return Value Method
BBjMenuBar addMenuBar()
boolean addOuterStyle(string cssClassName)
boolean addTitleBarStyle(string styleName)
void clearOuterStyles()
void clearTitleBarStyles()
void destroy()
string getComputedOuterStyle(string cssPropertyName)
int getMaximumHeight()
int getMaximumWidth()
BBjMenuBar getMenuBar()
int getMinimumHeight()
int getMinimumWidth()
int getNominalHeight()
int getNominalWidth()
int getOuterHeight()
string getOuterStyle(string cssPropertyName)
BBjVector getOuterStyles()
int getOuterWidth()
int getOuterX()
int getOuterY()
String getTitle()
BBjVector getTitleBarStyles()
BBjWindowValues getValues()
String getWindowMode()
boolean isAlwaysOnTop()
boolean isDesktopModal()
boolean isMaximized()
boolean isMinimized()
boolean isModal()
boolean isResizable()
boolean isTitleBarVisible()
void maximize()
void minimize()
boolean removeOuterStyle(string cssClassName)
boolean removeTitleBarStyle(string styleName)
void restore()
void setAlwaysOnTop()
void setMaximumSize(int maximumWidth, int maximumHeight)
void setMinimumSize(int minimumWidth, int minimumHeight)
void setOuterStyle(string cssPropertyName, string cssPropertyValue)
void setResizable(boolean resizable)
void setTitle(string title)
void setTitleBarVisible(boolean visible)

Methods of BBjTopLevelWindow implemented for MouseWheelEnabled

Return Value Method
int getScrollWheelBehavior()
void setScrollWheelBehavior(int trav)

Methods of BBjTopLevelWindow inherited from BBjWindow

Methods of BBjTopLevelWindow inherited from BBjControl

Events

BUI logoCSS

The visual appearance of BUI controls is defined using CSS (cascading style sheets) rules. Easily change the default colors, border, and other settings by customizing these rules, all without changing any application code. See CSS API for a high-level overview of BUI CSS.

The next level contains a BBjTopLevelWindow-titleBar structure and a BBjTopLevelWindow container. In BBj 13.0 and higher, the title bar can be hidden (see setTitleBarVisible). By hiding the title bar, eliminating all window borders (shown below) and maximizing the window, a BUI window can be made to completely blend into the browser. This makes the BUI application look less like a desktop application running in a browser and more like a typical web page.

In BBj 16 and higher, setting the FULL_WIDTH_TITLE !OPTIONS setting to TRUE expands the title bar tab of BUI windows docked to the top of the browser to take up the full defined width of the window.  By default, the BUI window title bar tab is just wide enough to contain the title text and any minimize, maximize, and close buttons.

The top level window and associated title bar have the following style names (note the space in the middle):

.BBjTopLevelWindow

.BBjTopLevelWindow.bbj-undecorated (the title bar is hidden)

.BBjTopLevelWindow.bbj-maximized (the window is maximized)

.BBjTopLevelWindow-titleBar

.BBjTopLevelWindow-titleBar .bbj-minimize

.BBjTopLevelWindow-titleBar .bbj-maximize

.BBjTopLevelWindow-titleBar .bbj-close

.BBjTopLevelWindow-titleBar-hidden

.BBjTopLevelWindow-titleBar-content-hidden

When form validation is active (from the instant the user clicks a button with a callback registered for the ON_FORM_VALIDATION event until the application clears the form validation state by calling BBjFormValidationEvent::accept), the BBjTopLevelWindow is overlaid with a translucent panel that blocks user input. This panel has the style name .BBjTopLevelWindow-validation.

Remarks

All BBjControl objects are created via a window object. Except for the tree, all controls created with object syntax can also be manipulated with mnemonics and sendmsgs. They are identical to the controls created with mnemonics or in a resource. All events for the controls will still be generated.

As of BBj 8, HTML in GUI controls implements the W3C standard for units such as 'em', 'px', and 'pt'. It also applies scaling factors from the 'SCALE' mnemonic and the SYSGUI DPI mode. Set the INCONSISTENT_HTML_FONTS !COMPAT setting to TRUE before creating the BBjTopLevelWindow to cause GUI controls on that top level window to ignore these settings when setting HTML content.

Constants

None.

Example

rem ' BBjTopLevelWindow

sysgui = UNT
open (sysgui)"X0"
sysgui! = bbjapi().getSysGui()
window! = sysgui!.addWindow(300,300,400,400,"BBjSysGui::addWindow",$00010003$)
window!.setCallback(window!.ON_CLOSE,"eoj")
legacy$ = iff(pos("TRUE"=stbl("!COMPAT","LEGACY_WINDOW_POSITION")),$0004$,$0000$)
legacy! = window!.addCheckBox(101,25,25,350,25,"LEGACY_WINDOW_POSITION",legacy$)
legacy!.setCallback(legacy!.ON_CHECK_ON,"legacy_true")
legacy!.setCallback(legacy!.ON_CHECK_OFF,"legacy_false")
resizable! = window!.addCheckBox(102,25,75,350,25,"Resizable",$$)
resizable!.setCallback(resizable!.ON_CHECK_ON,"resizable_on")
resizable!.setCallback(resizable!.ON_CHECK_OFF,"resizable_off")
closebox! = window!.addCheckBox(103,25,125,350,25,"Close Box",$$)
closebox!.setCallback(closebox!.ON_CHECK_ON,"closebox_on")
closebox!.setCallback(closebox!.ON_CHECK_OFF,"closebox_off")
menubar! = window!.addCheckBox(104,25,175,350,25,"Menu Bar",$$)
menubar!.setCallback(menubar!.ON_CHECK_ON,"menubar_on")
menubar!.setCallback(menubar!.ON_CHECK_OFF,"menubar_off")
titlebar! = window!.addCheckBox(105,25,225,350,25,"Title Bar",$0004$)
titlebar!.setCallback(titlebar!.ON_CHECK_ON,"titlebar_on")
titlebar!.setCallback(titlebar!.ON_CHECK_OFF,"titlebar_off")
addWindow! = window!.addButton(1,25,350,350,25,"addWindow",$$)
addWindow!.setCallback(addWindow!.ON_BUTTON_PUSH,"addWindow")
x = 100
y = 100
w = 200
h = 200
title$ = "window"
flags$ = $00000000$
process_events

eoj:
release

legacy_true:
    print stbl("!COMPAT","LEGACY_WINDOW_POSITION=TRUE")
return

legacy_false:
    print stbl("!COMPAT","LEGACY_WINDOW_POSITION=FALSE")
return

resizable_on:
    flags$ = ior(flags$,$00000001$)
    print hta(flags$)
return

resizable_off:
    flags$ = AND(flags$,not($00000001$))
    print hta(flags$)
return

closebox_on:
    flags$ = ior(flags$,$00000002$)
    print hta(flags$)
return

closebox_off:
    flags$ = AND(flags$,not($00000002$))
    print hta(flags$)
return

menubar_on:
    flags$ = ior(flags$,$00000800$)
    print hta(flags$)
return

menubar_off:
    flags$ = AND(flags$,not($00000800$))
    print hta(flags$)
return

titlebar_on:
    flags$ = AND(flags$,not($01000000$))
    print hta(flags$)
return

titlebar_off:
    flags$ = ior(flags$,$01000000$)
    print hta(flags$)
return

addWindow:
    context = sysgui!.getAvailableContext()
    addWindow! = sysgui!.addWindow(context,x,y,w,h,title$,flags$)
    addWindow!.setCallback(addWindow!.ON_CLOSE,"destroy")
    destroy! = addWindow!.addButton(2,25,25,100,25,"Destroy",$$)
    destroy!.setCallback(destroy!.ON_BUTTON_PUSH,"destroy")
return

destroy:
    event! = sysgui!.getLastEvent()
    control! = event!.getControl()

    if (control!.isDestroyed()) then
    return
endif

window! = control!.getParentWindow()

if (window!.isDestroyed()) then
    return
endif

window!.destroy()
return

See Also

BBjAPI

BBjSysGui

See the BBj Object Diagram for an illustration of the relationship between BBj Objects.