BBMig Layout Manager Overview

Description

In BBj 15.0 and higher, BBMig is a powerful and flexible layout manager built upon the open source MigLayout library. By integrating the layout manager into your graphical applications you can ensure that your user interfaces conform to the available screen space in adherence to the constraints defined for the container, rows, and columns. This results in GUI controls that are automatically sized and positioned within the window, regardless of the window size or the platform upon which the program is running. BBMig uses string-based constraints, making the layout code portable, concise, human readable, and easy to implement.

For complete BBMig documentation click here.

Capabilities

In addition to controlling the layout of controls, BBMig also provides the ability to scale layouts. This makes it possible to zoom in and out of a form, similar to how browsers can zoom on a page to enlarge the text making it easier to read. Scaling the layout down in effect zooms out, decreasing the size of windows and their controls to consume less screen space.

BBMig also offers the optional handling of platform specific label justification and standard button sequencing. This simplifies the task of providing control layouts that are consistent with the target platform without having to query the target operating system or provide any extra code logic. Named tags, such as 'help', 'ok', and 'cancel' ensure that the buttons in the screenshots below will be placed in accordance with the target operating system's user interface guidelines.

The third screenshot with the dotted red and blue lines shows how BBMig's debug mode can be used to easily visualize the bounds of the layout manager's grid cells and components, respectively.

Sample Program Running on OS X, with Help Button on Left

Sample Program Running on Windows with Help Button on Right

Sample Program With Debug Mode On

Helpful Links

The following links provide useful information for the MigLayout library. While the actual BBj implementation code will be slightly different, all of the information contained in the documents that refer to concepts and constraints is immediately applicable to BBMig.

MigLayout Whitepaper

MigLayout Quick Start Guide

MigLayout Cheat Sheet

Sample BBj Program

use com.basiscomponents.ui.layout.BBMigPane
use net.miginfocom.layout.PlatformDefaults
use java.util.HashMap
use java.util.Iterator

rem 'test code when run
rem 'debug = BBjAPI().TRUE
new bbmigtest(debug)
release

class public bbmigtest

    field private BBjAPI    API! = BBjAPI()
    field private BBjNumber TRUE = BBjAPI().TRUE
    field private BBjNumber FALSE = BBjAPI().FALSE
    field private BBjSysGui SysGui! = BBjAPI().openSysGui("X0")
    field private BBjNumber debug = BBjAPI().FALSE
    field private BBjTopLevelWindow Window!
    field private BBMigPane Layout!
    field private BBjChildWindow cWindow!
    field private BBMigPane cLayout!
    field private BBjStaticText lFirstName!
    field private BBjInputE iFirstName!
    field private BBjStaticText lSurname!
    field private BBjInputE iSurname!
    field private BBjStaticText lAddress!
    field private BBjInputE iAddress!
    field private BBjMenuButton bOk!
    field private BBjMenuButton bCancel!
    field private BBjMenuButton bHelp!
    field public BBjNumber ActiveResize = BBjAPI().FALSE

    method public bbmigtest()
        #bbmigtest(BBjAPI().FALSE())
    methodend

    method public bbmigtest(BBjNumber debug)
        #debug = debug
        if (#debug) then
            print 'show',

            rem 'test platforms (NOTE: setting sticks til reset or JVM re-started)
            rem 'PlatformDefaults.setPlatform(PlatformDefaults.WINDOWS_XP)
            rem 'PlatformDefaults.setPlatform(PlatformDefaults.MAC_OSX)
            rem 'PlatformDefaults.setPlatform(PlatformDefaults.GNOME)
            print "Platform=",
            switch PlatformDefaults.getPlatform()
                case PlatformDefaults.WINDOWS_XP
                    print "Windows",
                break
                case PlatformDefaults.MAC_OSX
                    print "Mac OS X",
                break
                case PlatformDefaults.GNOME
                    print "Gnome",
                break
                case default
                    print "Unknown",
                break
            swend
            print " (real os=",System.getProperty("os.name"),"), Default DPI=",
            :               PlatformDefaults.getDefaultDPI()
        else
            print 'hide',
        endif
        #constructForm()
        #show()
    methodend

    method public void show()
        #Window!.setCallback(#Window!.ON_CLOSE, #this!, "closeWindow")
        #Window!.setCallback(#Window!.ON_RESIZE, #this!, "windowResize")
        #Window!.setCallback(#Window!.ON_SCREEN_RESIZE, #this!, "screenResize")
        #Window!.setCallback(#Window!.ON_MOUSE_SCROLL, #this!, "mouseScroll")
        #cWindow!.setCallback(#cWindow!.ON_MOUSE_SCROLL, #this!, "mouseScroll")
        #resizeTimerEvent(null())
        #Window!.setVisible(#TRUE)
        #Window!.focus()
        process_events
    methodend

    method public void closeWindow(BBjCloseEvent ev!)
        release
    methodend

    method public void windowResize(BBjResizeEvent p_event!)
        if !(#ActiveResize)
            #ActiveResize = #TRUE
            #API!.createTimer("ResizeEventTimer", .2, #this!, "resizeTimerEvent")
        endif
    methodend

    method public void screenResize(BBjScreenResizeEvent p_event!)
        if !(#ActiveResize)
            #ActiveResize = #TRUE
            #API!.createTimer("ResizeEventTimer", .2, #this!, "resizeTimerEvent")
        endif
    methodend

    method public void resizeTimerEvent(BBjTimerEvent p_event!)
        #SysGui!.setRepaintEnabled(#FALSE)
        #Layout!.layoutChildren()
        #cLayout!.layoutChildren()
        #SysGui!.setRepaintEnabled(#TRUE)
        #API!.removeTimer("ResizeEventTimer",err=*next)
        #ActiveResize = #FALSE
    methodend

    method public void mouseScroll(BBjScrollWheelEvent p_event!)
        if (p_event!.isControlDown() or p_event!.isCmdDown()) then
            scale = num(cast(HashMap, #Window!.getUserData()).get("scale"))
            if (p_event!.getScrollDirection()) then
                scale = scale + (p_event!.getWheelRotation() / 10)
            else
                scale = scale - (p_event!.getWheelRotation() / 10)
            endif
            if (scale >= 0.5 and scale <= 4.0) then
                #Layout!.scaleLayout(scale, #SysGui!)
                #cLayout!.scaleLayout(scale, #SysGui!)
                cast(HashMap, #Window!.getUserData()).put("scale", scale)
            endif
        endif
    methodend

    method public void constructForm()
        WinFlags$=$00000000$
        WinFlags$=IOR(WinFlags$,$00000001$); rem Resizable
        WinFlags$=IOR(WinFlags$,$00000002$); rem Include close box

        rem 'WinFlags$=IOR(WinFlags$,$00000004$); rem Horizontal scroll bar
        rem 'WinFlags$=IOR(WinFlags$,$00000008$); rem Vertical scroll bar
        WinFlags$=IOR(WinFlags$,$00000010$); rem Initially invisible

        rem 'WinFlags$=IOR(WinFlags$,$00000020$); rem Initially disabled
        WinFlags$=IOR(WinFlags$,$00000080$); rem Max-/Minimizable

        rem 'WinFlags$=IOR(WinFlags$,$00000100$); rem Initially minimized
        rem 'WinFlags$=IOR(WinFlags$,$00000800$); rem Include menu bar
        rem 'WinFlags$=IOR(WinFlags$,$00001000$); rem Initially maximized
        rem 'WinFlags$=IOR(WinFlags$,$00002000$); rem No menu separator line
        WinFlags$=IOR(WinFlags$,$00010000$); rem Keyboard navigation

        rem 'WinFlags$=IOR(WinFlags$,$00020000$); rem Always on top
        rem 'WinFlags$=IOR(WinFlags$,$00040000$); rem Dialog border
        WinFlags$=IOR(WinFlags$,$00080000$); rem Behave as a dialog

        rem 'WinFlags$=IOR(WinFlags$,$00100000$); rem Auto-arrange controls
        WinFlags$=IOR(WinFlags$,$00400000$); rem Custom color palette
        WinFlags$=IOR(WinFlags$,$00800000$); rem <Enter> behaves as <Tab>

        rem 'WinFlags$=IOR(WinFlags$,$01000000$); rem No window title bar
        WinFlags$=IOR(WinFlags$,$04000000$); rem Auto-manage SYSCOLOR events

        rem 'WinFlags$=IOR(WinFlags$,$20000000$); rem (VPRO5) Report mouse right button
        rem 'WinFlags$=IOR(WinFlags$,$40000000$); rem MDI group-modal
        #Window! = #SysGui!.addWindow(
        :           #SysGui!.getAvailableContext(),400,400,400,400,
        :           "BBMigPane Layout Test",WinFlags$)
        #Window!.setName("window")
        #Window!.setUserData(new HashMap())
        cast(HashMap, #Window!.getUserData()).put("scale",1.0)
        declare BBjFont font!
        font_size = 12
        font! = #SysGui!.makeFont("Dialog",font_size,#SysGui!.PLAIN)
        font_height = iff(font!.getStyle()=#SysGui!.BOLD,int(font_size*1.1),font_size)
        #Window!.setFont(font!)
        if #debug then #Window!.setTrack(BBjAPI().FALSE)
        #Layout! = new BBMigPane(#Window!,
        :           "insets dialog"+iff(#debug,", debug",""),
        :           "[align label]rel[grow,fill]unrel[align label]rel[grow,fill]",
        :           "")
        declare BBjVector tx!
        declare BBjVector tm!
        tx! = #API!.makeVector()
        tidFirstName = 0; tx!.add(tidFirstName, "First Name:")
        tidSurname = 1; tx!.add(tidSurname, "Surname:")
        tidAddress = 2; tx!.add(tidAddress, "Address:")
        tidOk = 3; tx!.add(tidOk, "OK")
        tidCancel = 4; tx!.add(tidCancel, "Cancel")
        tidHelp = 5; tx!.add(tidHelp, "Help")
        tm! = #SysGui!.getMeasures(tx!)
        declare BBjColor lbl_bkcolor!
        lbl_bkcolor! = #API!.makeColor(#SysGui!.YELLOW)
        setlblbkcolor = #debug

        rem 'label width/height padding, input control width/height padding
        lwpad=0,lhpad=8,iwpad=8,ihpad=8
        #lFirstName! =  #Window!.addStaticText(#Window!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidFirstName))+lwpad,font_height+lhpad,
        :           str(tx!.get(tidFirstName)))
        #lFirstName!.setName("lFirstName")
        #lFirstName!.setOpaque(#FALSE)
        #lFirstName!.setFont(font!)
        if setlblbkcolor then #lFirstName!.setBackColor(lbl_bkcolor!)
        #Layout!.add(#lFirstName!)
        #iFirstName! = #Window!.addInputE(#Window!.getAvailableControlID(),0,0,
        :           100,font_height+ihpad,"")
        #iFirstName!.setName("iFirstName")
        #iFirstName!.setFont(font!)
        #Layout!.add(#iFirstName!)
        #lSurname! = #Window!.addStaticText(#Window!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidSurName))+lwpad,font_height+lhpad,str(tx!.get(tidSurName)))
        #lSurname!.setName("lSurname")
        #lSurname!.setOpaque(#FALSE)
        #lSurname!.setFont(font!)
        if setlblbkcolor then #lSurname!.setBackColor(lbl_bkcolor!)
        #Layout!.add(#lSurname!)
        #iSurname! = #Window!.addInputE(#Window!.getAvailableControlID(),0,0,
        :           100,font_height+ihpad,"")
        #iSurname!.setName("iSurname")
        #iSurname!.setFont(font!)
        #Layout!.add(#iSurname!, "wrap")
        #lAddress! = #Window!.addStaticText(#Window!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidAddress))+lwpad,font_height+lhpad,str(tx!.get(tidAddress)))
        #lAddress!.setName("lAddress")
        #lAddress!.setOpaque(#FALSE)
        #lAddress!.setFont(font!)
        if setlblbkcolor then #lAddress!.setBackColor(lbl_bkcolor!)
        #Layout!.add(#lAddress!)
        #iAddress! = #Window!.addInputE(#Window!.getAvailableControlID(),0,0,
        :           200,font_height+ihpad,"")
        #iAddress!.setName("iAddress")
        #iAddress!.setFont(font!)
        #Layout!.add(#iAddress!, "spanx, wrap unrel:push")

        rem 'child window (pane) for the buttons to test button tags
        cWinFlags$=$00000000$

        rem 'cWinFlags$=IOR(cWinFlags$,$00000004$); rem Allow horizontal scroll bar
        rem 'cWinFlags$=IOR(cWinFlags$,$00000008$); rem Allow vertical scroll bar
        rem 'cWinFlags$=IOR(cWinFlags$,$00000010$); rem Initially invisible
        rem 'cWinFlags$=IOR(cWinFlags$,$00000020$); rem Initially disabled
        cWinFlags$=IOR(cWinFlags$,$00000800$); rem No border
        cWinFlags$=IOR(cWinFlags$,$00010000$); rem Keyboard navigation

        rem 'cWinFlags$=IOR(cWinFlags$,$00100000$); rem Auto-arrange controls
        rem 'cWinFlags$=IOR(cWinFlags$,$00200000$); rem Dock in parent frame
        cWinFlags$=IOR(cWinFlags$,$00800000$); rem <Enter> behaves as <Tab>

        rem 'cWinFlags$=IOR(cWinFlags$,$01000000$); rem Recessed client edge
        rem 'cWinFlags$=IOR(cWinFlags$,$02000000$); rem Raised edge
        #cWindow! = #Window!.addChildWindow(#Window!.getAvailableControlID(),0,0,
        :           #Window!.getWidth(),25,"",cWinFlags$,#SysGui!.getAvailableContext())
        #cWindow!.setName("cWindow")
        #cWindow!.setFont(font!)
        declare BBjColor btn_bkcolor!
        btn_bkcolor! = #API!.makeColor(#SysGui!.CYAN)
        setbtnbkcolor = #debug
        if #debug then #cWindow!.setTrack(BBjAPI().FALSE)
        #cLayout! = new BBMigPane(#cWindow!, "nogrid, fill"+iff(#debug,", debug",""))
        bwpad=16,bhpad=16; rem button width/height padding
        #bHelp! = #cWindow!.addMenuButton(#cWindow!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidHelp))+bwpad,font_height+bhpad,str(tx!.get(tidHelp)))
        #bHelp!.setName("bHelp")
        #bHelp!.setBorderPainted(#TRUE)
        #bHelp!.setFont(font!)
        if setbtnbkcolor then #bHelp!.setBackColor(btn_bkcolor!)
        #cLayout!.add(#bHelp!,"sg,tag help");rem there is also a "tag help2"
        #bOk! = #cWindow!.addMenuButton(#cWindow!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidOk))+bwpad,font_height+bhpad,str(tx!.get(tidOk)))
        #bOk!.setName("bOk")
        #bOk!.setBorderPainted(#TRUE)
        #bOk!.setFont(font!)
        if setbtnbkcolor then #bOk!.setBackColor(btn_bkcolor!)
        #cLayout!.add(#bOk!,"sg,tag ok")
        #bCancel! = #cWindow!.addMenuButton(#cWindow!.getAvailableControlID(),0,0,
        :           num(tm!.get(tidCancel))+bwpad,font_height+bhpad,str(tx!.get(tidCancel)))
        #bCancel!.setName("bCancel")
        #bCancel!.setBorderPainted(#TRUE)
        #bCancel!.setFont(font!)
        if setbtnbkcolor then #bCancel!.setBackColor(btn_bkcolor!)
        #cLayout!.add(#bCancel!,"sg,tag cancel")
        #cLayout!.layoutChildren()
        #Layout!.add(#cWindow!, "south")
    methodend

classend