|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.
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.
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.