B4J Tutorial [BANanoWebix] Lesson 5: Creating ToolBars

Hi

This 5th installment of webix tuts deals with how one can create toolbars. These sit on the Rows collection of your page and can have a variety of elements like buttons, toggle buttons and icons.

Like any WixElement, one can set the height of the toolbar and also set some default configuration that will be applied to the child elements.

In this session, we will do the following:

1. Add a header title to our page with 'Lesson 5: WixToolBar'
2. Create a toolbar and add buttons, toggles and icons to it and bind some events to the buttons
3. Add the toolbar to the page
4. Show a 'message' and also explore the Confirm dialog box available in Webix.

The code module for this exercise is pgToolbar.

Adding the header

pg.Initialize("")
    '
    'create a header to add to the page
    Dim hdr As WixHeader
    hdr.Initialize("hdr")
    hdr.Header.SetTemplate("Lesson 5: WixToolBar")
    hdr.Header.AddToRows(pg.Page)

We initialize our page and easily define a WixHeader and set the template and add this to the Rows Collection of the WixPage element.

 

[Mashiane]

Creating the toolbar

The process of creating the toolbar is straighforward and simple, one defines it and then adds the needed elements to it. Remember, all BANanoWebix elements are based on the WixElement. This element has been evolving as we have been exploring this framework and also very consistent.

'create a toolbar
    Dim tblBar As WixToolBar
    tblBar.Initialize("")
    'set the height of the toolbar and the batch of controls to be visible on init
    tblBar.ToolBar.SetHeight(60).SetVisibleBatch(1)
    'settings to be applied to each element added to the toolbar
    tblBar.ToolBar.SetDefaultWidth(90).SetDefaultTypeIconButton

We have initialized a toolbar, we want to limit its height to 60px. This means that any element that we add to it will be having a height limited to that.

Now comes SetVisibleBatch(1)

The visibleBatch attribute is used when you want to show / hide a group of elements. You assign a batch number to them and when that batch is indicated for visibility, it becomes visible / hidden. So here we are saying, only show all elements with a batch number = 1.

We then set the default width of child elements to 90px with SetDefaultWidth and set the type of buttons to use to be iconButtons. When not specifying default settings for child elements, one can use SetWidth and SetHeight & SetType for each element.

We will explore the .SetDefaultXXX methods when we deal with Form Data Entry in our next lesson.

After all the child elements for the toolbar are added, we add it to the page with tblBar.AddToPage(pg)

Let's look at the buttons, icons, toggle buttons etc for the toolbar.

 

[Mashiane]

Adding Buttons to the Toolbar

At the heart of a normal button is the Label/Value, the width & height, the type of button it is and the click event.

There is a variety of buttons that you can create: These are depicted in this enumeration class.

Public ButtonBase As String = ""
    Public ButtonDanger As String = "danger"
    Public ButtonForm As String = "form"
    Public ButtonPrev As String = "prev"
    Public ButtonNext As String = "next"
    Public ButtonImage As String = "image"
    Public ButtonIconButton As String = "iconButton"
    Public ButtonIconButtonTop As String = "iconButtonTop"
    Public ButtonImageButton As String = "imageButton"
    Public ButtonIcon As String = "icon"

This means we can add icons to buttons, add images, theme them to be 'red for danger' etc. This basically indicates the 'type' of element and will go to the wixelement.type property.

In the gif on the first post we have covered the normal buttons, image, iconbutton, iconbuttontop, imagebutton and icons.

There are two methods to add buttons to the toolbar...
1. either we initialize it and then add it to the toolbar
2. either we use the .CreateButton / .CreateToggle / .CreateIcon methods of the toolbar and then .Pop these to the toolbar.

The New Button

tblBar.CreateButton("btnNew").SetLabel("New").SetIcon("file").SetClick(BANano.CallBack(Me,"btnnew_click",Null)).SetBatch(1).Pop

The new button is created using the toolbar CreateButton method. We id the button is btnNew, then set its label/value to New. We then set its icon () using .SetIcon.
After that we bind a click event to it using a BANano.Callback call. The method to be called when the button is clicked is btnnew_click.
When we were creating the toolbar, we indicated that the visibleBatch should be 1. So setting the batch number to 1 for this button will ensure that it shows.
Using .CreateButton ensures that the parent element of the component is linked, thus its easy to have a method like .Pop to populate the button and add it to the Columns collection of the toolbar.

The Open Button

The Open button is created via the second method, ie. initialize the button and then add it to the toolbar.

Dim btnOpen As WixButton
    btnOpen.Initialize("btnOpen").SetLabel("Open").SetIcon("folder-open").SetBatch(2).SetClick(BANano.CallBack(Me,"btnopen_click",Null)).AddToToolbar(tblBar)
'

Nothing is very different from the calls we made earlier to create the new button except for .SetBatch(2) and .AddToToolBar(tblBar) here. We initialized the button and set some properties and then added it to the toolbar. Because the batch number of this button is 2 and our .SetVisibleBatch = 1 this button will not be shown on creation as its a child element of the toolbar with a different visible batch number.

 

[Mashiane]

Adding Toggle Buttons / Icons

tblBar.AddSpacer
    '
    'create toggle buttons
    tblBar.CreateToggle("imgt3").SetTypeIcon("").SetOffIcon("wxi-close").SetOnIcon("wxi-check").SetLabel("Music").Pop
    tblBar.CreateToggle("imgt4").SetTypeIconButtonTop("").SetIcon("wxi-sync").SetOnLabel("Wi-Fi On").SetOffLabel("Wi-Fi Off").Pop
    tblBar.AddSpacer
    tblBar.CreateButton("btnImage").SetLabel("Image").SetTypeImage("").SetWidth(150).SetImage("./assets/icons8-save-as-100.png").Pop
    tblBar.CreateButton("btnImageButton").SetLabel("ImageButton").SetTypeImageButton("").SetImage("./assets/icons8-compose-40.png").SetWidth(40).Pop
    tblBar.CreateButton("btnIcon").SetTypeIcon("").SetIcon("wxi-file").SetWidth(200).SetLabel("File Name").Pop
    '
    tblBar.AddSpacer
    '
    'create icons
    Dim icn As WixIcon
    icn.Initialize("icn").SetIcon("wxi-angle-up").SetClick(BANano.CallBack(Me,"up_click",Null)).AddToToolbar(tblBar)
    '
    tblBar.CreateIcon("icn1").SetIcon("wxi-angle-down").SetClick(BANano.CallBack(Me,"down_click",Null)).Pop
    '

A toggle button is another instance of the button but with .SetToggle(True) being executed, so one can initialize a button and then call .SetToggle(True) to it. For the toggles on the toolbar here we have used the .CreateToggle method. A toggle button has 2 states, on and off / checked and unchecked. For them, one is able to set the OnLabel/OffLabel, OnIcon/OffIcon.

For example, we create a button with the label Wi-Fi with an OnIcon and OffIcon, so when a user clicks this button the toggle state fires and behaves accordingly.

We continue to add other sorts of buttons with images, and one button has an icon sitting on top due to .SetTypeIconButtonTop.

There are also two icons we have added to the page, as noted, these do not have any borders and have arrows pointing up / down. One is created with .CreateIcon and the other with an initialize method.

You can link events to the buttons as indicated with the click attribute. As noted, we have linked some buttons so that a message appears when they are clicked.

Sub Up_click
    pg.Message("up")
End Sub

Sub Down_click
    pg.ToastError("Down!")
End Sub

Sub btnNew_click
    pg.Message("btnNew_click")
End Sub

Sub btnOpen_click
    pg.Message("btnOpen_click")
End Sub

Sub btnSave_click
    pg.Message("btnSave_click")
End Sub

The .ToastError page method on the other hand shows a 'red' toast on the page. This can be used for errors and warnings..

 

[Mashiane]

Confirm Dialog

One of the buttons in the toolbar is rather interesting, btnClose

tblBar.CreateButton("btnClose").SetLabel("Close").SetIcon("window-close").SetBatch(1).SetClick(BANano.CallBack(Me,"btnclose_click",Null)).AddToToolbar(tblBar)

When this is clicked, the btnclose_click sub should be fired. Looking closely at that sub, we notice that this fires a .Confirm method of the page. This is how we execute confirm prompts. These come with Cancel = False and OK = True that we trap.

Sub btnClose_click
    Dim result As Boolean = False
    Dim cb As BANanoObject = BANano.CallBack(Me,"closeresult",Array(result))
    pg.Confirm(cb, "Confirm Close", "Are you sure that you want to close?")
End Sub

A confirm dialog ALWAYS returns a result boolean variable, false on cancel and true on ok. Thus we have defined a callback event that we pass to the .Confirm method with a title and the prompt message.

In this instace we are saying, the result of the selected propmpt, whether yes/no should be passed to a callback method called "closeresult"

'callback should be ConfirmResult_{Tag}
Sub closeresult(result As Boolean)
    pg.Message(result)
End Sub

This means one can create various confirm dialogs and link them to own respective call back methods to process the Cancel (False) or OK(True) results chosen by end users.

As we will be starting with Form Data Entry soon, we will explore more how the .SetVisibleBatch method works and how the various input elements can be added, set, get etc. For now this covers the layouts of the basic version of Webix that can be used mostly.

NB: There are a lot of properties and methods for elements in this lib, I'm just picking up stuff that can be easily usable for one to have apps working quickly. As its open source (BANanoWebix) one can extend it whatever way they wish to meet their needs.

Fork it here