SetHeaderCaption - cWebView

Parameter	Description
sCaption	The caption text

Procedure SetHeaderCaption String sCaption

Call:

Send SetHeaderCaption sCaption

SetHeaderCaption sets the value of the breadcrumb control's (cWebBreadcrumb) header section during forward navigation.

The messages SetHeaderCaption, SetBreadCrumbCaption, GetHeaderCaption, GetBreadCrumbCaption, psCaption and pbShowCaption are all used to control view captions.

Understanding cWebView Captions

Captions with Desktop style web views

With a desktop style web view (peWebViewStyle = wvsDesktop), the view caption process is simple. The psCaption web property is used to display the caption, which, depending on the theme being used, will display some kind of caption at the top of the view. As with any web property, the default value is defined with the Set command, which can be customized on a client/user basis with the WebSet command.

The pbShowCaption web property determines if the caption should be displayed. By default, it is True, so a caption will be displayed. A typical desktop style view's code will look like this:

Object oCustomer is a cWebView
    Set piColumnCount to 10
    Set psCaption to "Customer Maintenance"
    Set piWidth to 600
    :

SetBreadCrumbCaption, SetHeaderCaption, GetBreadCrumbCaption and GetHeaderCaption are not used with desktop style web views.

Captions with Mobile/Touch style web views

With a mobile style web view (peWebViewStyle = wvsDrilldown), the view caption process is a bit more complicated. A mobile view actually has three places where a "caption" may appear:

1. View Caption - this is the same as the desktop caption. It is a caption line that appears inside the view.
2. Header Caption - this is text that will appear in the header bar of a breadcrumb control
3. Breadcrumb Caption - this is the text that appears in the "breadcrumb" trail. Depending on the mobile device, this trail will be displayed in a horizontal list or as a dropdown list.

The breadcrumb control is managed automatically by a cWebViewStack object and a cWebBreadcrumb object.

By default, all three of these captions are assigned the same value, psCaption.

In a typical mobile view, the View Caption will be hidden by setting pbShowCaption to False. This is done because its content will be duplicated in the other caption areas. Therefore, a typical view will look like this:

Object oSelectCustomer is a cWebView
    Set psCaption to "Customers"
    Set pbShowCaption to False
    Set piMaxWidth to 1024
    Set piColumnCount to 6
    :

In the above example, the view caption will be hidden while the header caption and breadcrumb caption will show "Customers". If you set pbShowCaption to True, you see the same caption in your view as well.

You can create custom text for view, header and breadcrumb captions. Since drilldown style views can be navigated to from any number of invoking views, a mechanism has been created that allows you to change these captions dynamically -- both while the view is being navigated-to and while the view is displayed. That is done with SetHeaderCaption, SetBreadCrumbCaption and psCaption (using WebSet).

Any time a view is being navigated-to (NavigateForward) all captions are reset to their "default" value set by psCaption. This is the value set using the Set command and not WebSet. If psCaption has been WebSet to a different value, it is re-WebSet back to its original value. Therefore, upon entering the view's OnNavigateForward event, the three captions will be the same. You can use OnNavigateForward to customize these values using the messages SetHeaderCaption, SetBreadCrumbCaption and (WebSet) psCaption. Consider the following example:

Object oSelectCustomer is a cWebView
    Set psCaption to "Generic Caption"
    Set pbShowCaption to True
    :

    Procedure OnNavigateForward tWebNavigateData NavigateData Handle hoInvokingView Handle hoInvokingObject
        WebSet psCaption to "Caption"
        Send SetBreadCrumbCaption "BreadCrumb"
        Send SetHeaderCaption     "Header"
        :

In the above example, the view caption will be "Caption", the header caption will be "Header" and the breadcrumb caption will be "BreadCrumb". In this case, the default caption, "Generic Caption" has been replaced for each caption.

Here is another, more real world, example:

Object oZoomCustomer is a cWebView
    Set peViewType to vtZoom 
    Set psCaption to "Customer Maintenance"
    Set pbShowCaption to False
    :

    Procedure OnNavigateForward tWebNavigateData NavigateData Handle hoInvokingView Handle hoInvokingObject
        Boolean bHasRecord
        Get HasRecord of oCustomer_DD to bHasRecord
        If bHasRecord Begin
            Send SetBreadCrumbCaption (Trim(customer.Name))
        End
        Else Begin
            Send SetBreadCrumbCaption "New Customer"
        End
    End_Procedure

In this example, the header caption will be "Customer" and the breadcrumb caption will be the customer's name or, if new, "New Customer". The view caption is not shown; if it were, it would show "Customer". This shows how these messages can be used to create dynamic captions.

As a final example, we could use the OnViewCleared event, which is called after a clear, to change the breadcrumb caption from a customer name to "New Customer".

    Procedure OnViewCleared Handle hoDDO
        Send SetBreadCrumbCaption "New Customer"
    End_Procedure

You may use GetHeaderCaption, GetBreadCrumbCaption and (WebGet) psCaption to get the current caption values of an active view. You may use Get psCaption to get the design-time default caption which is applied to all of these captions when a view is navigated-to.