xch_pane

This tag may be used to open and close Pueblo panes. Panes can either display static HTML documents served over the Web via HTTP or dynamic HTML from a world server, using the pane redirect feature described below.

Pane redirection

Redirection is a powerful feature designed by Chaco to allow world authors to send information directly to a new or existing pane. For example, when action=redirect and name=bob is specified, then all data that appears in the stream following the tag will be displayed in pane “bob”.

Internally the HTML engine maintains a redirection stack which allows the author to specify certain reserved name attributes to control redirection. Some special names may be used to access this redirection stack. name=_previous will cause the redirection to stop in the current pane and all data to appear in the last pane that received redirection. Specifying name=_top will clear the redirection stack and the data stream is redirected to the default view.

Here is an example of redirection:

Data sent from world:
Behavior:
This is the main pane.
Initially, all output goes to the Pueblo log window. This string will appear in the log window.
<xch_pane action=redirect name=mylog>
This opens a new window with the internal name “mylog” and begins sending all stream data to that window.
This is my private log pane.
This data will appear in the new pane named “mylog”.
<xch_pane action=redirect name=book>
This opens a new window with the internal name “book” and begins sending all stream data to that window.
This is my book pane.
This data will appear in the new pane named “book”.
<xch_pane action=redirect name=_previous>
This switches redirection to the previous pane in the stack. In this case, the previous pane is named “mylog”.
I really like my private log pane. It is my friend!
This data will appear in the new pane named “mylog”. If “mylog” was closed by the user after it was created, then the data is ignored and not displayed. (Note that the main Pueblo log window can never be closed by the user.)
<xch_pane action=redirect name=_top>
This switches output back to the Pueblo log window and removes all windows from the stack.
Back in the main pane!
This string will appear in the main log window.

Attributes

ACTION

This tag indicates which action should be taken, and may have the following values:

open
Opens a pane. The HTML string must include a href attribute indicating what should be displayed in the pane. If the action attribute is not specified, this is the default.
close
Closes a pane. If this value is used, the author must also specify a name attribute. (All other attributes to this command are ignored.)
redirect
Causes all stream data following this element to be sent to the TARGET pane. If the target pane does not exist and the OPTIONS=”existing” is specified, then the redirected text is discarded until the redirection target is changed.
If you specify the HREF attribute with this action, the data stream is not redirected and will continue to be processed in the current pane. The document specified by the URL will be appended to the existing pane. If the pane doesn’t exist then a new pane will be opened (unless OPTIONS=”existing” is specified.)

HREF

Indicates the file that should be loaded into the pane. If you use redirect, then the specified URL will be loaded, and the stream data will continue being redirected to the specified NAME pane.

NAME

The name of the pane. This name is used internally to reference the pane. If this attribute contains no value, then the pane will be created without a name and cannot be closed by the world author.

Pane names may be any short string starting with an alphabetic character. In addition, the following special names may be used:

_blank
When used with action=open and options=browser or options=webtracker, this causes an empty, unnamed pane to be created. This is the default value when this attribute is not specified. The following restrictions on this name apply:
1) This can be used only with action=open.
2) If options=browser is specified then the configured web browser is opened
3) If options=webtracker is specified then WebTracker is opened.
4) If options=browser or options=webtracker is not specified then a new nameless pane is opened only if HREF attribute is set.
_previous
When used with action=redirect, causes redirection to pass to the previous pane that received redirection.
_top
Causes redirection to be eliminated, so that data coming across goes to the main pane of the set. This does nothing when action=close.

This attribute must be specified when action=close.

PANETITLE

Specifies the window caption text. Note that the title is just for display, and may be any short descriptive string.

WIDTH

Suggested width for the pane. This value is used if the pane was not previously created and sized by the user. This value may be an integer number of pixels, or a percentage. If the pane is overlapped or floating, then this is a percentage of the screen height. If the pane is docked or internal, then this is a percentage of the client area.

HEIGHT

Suggested height for the pane. This value is used if the pane was not previously created and sized by the user. This value may be an integer number of pixels, or a percentage. If the pane is overlapped or floating, then this is a percentage of the screen height. If the pane is docked or internal, then this is a percentage of the client area.

MINWIDTH

Minimum allowable width for the pane. If the pane is sizeable by the user, the width may not be made smaller than this value. The value should be an integer number of pixels.

MINHEIGHT

Minimum allowable height for the pane. If the pane is sizeable by the user, the height may not be made smaller than this value. The value should be an integer number of pixels.

VSPACE

The number of pixel border that will be placed to the top and bottom of the contents of the pane. If this value is zero, then a default vertical border size will be used.

HSPACE

The number of pixel border that will be placed to the left and right of the contents of the pane. If this value is zero, then a default horizontal border size will be used.

SCROLLING

This attribute is used to describe if the frame should have a scrollbar or not. scrolling=yes results in scrollbars always being visible on that frame. scrolling=no results in scrollbars never being visible. scrolling=auto instructs the browser to decide whether scrollbars are needed, and place them where necessary. This attribute is optional; the default value is auto.

OPTIONS

This attribute specifies options for the pane. Attributes must be specified in a string delimited with spaces or commas. The following attributes are exclusive, and only one of these may be used:

overlapped
Creates a pane that is a peer of the main application. The pane may be moved to the back of the application by the user. May not be used with the floating, internal, or docking options.
floating
Creates a pane that floats above all non-floating pueblo client windows. May not be used with the overlapped, internal, or docking options.
internal
Causes an internal pane to be created. The pane is created at the top of the window unless the align=”bottom” option is specified. May not be used with the overlapped, floating, or docking options.
browser
Opens the user’s generic browser application. This may be WebTracker or another browser such as Netscape. Note that if this option is used, the sizing and alignment options will be ignored, as the browser may be a separate application.

In addition, a combination of the following attributes may be used:

nonsizeable
Creates a pane that may not be resized by the user.
noclose
Creates a pane that may not be closed by the user. This option is ignored for panes created as unnamed.
small_title
Creates a pane that has a smaller caption. These panes take slightly less space than normal panes.
fit
This option causes the pane to size to fit the contents of the pane. For more information on this option, see below.
persistent
Causes the pane to remember its last position and size.
force
Forces the location and size specified. A pane created with this option will not use the stored location by default. This option is only meaningful for persistent’ panes.
viewbottom
Causes the pane to scroll to the bottom whenever new data is appended. If an HREF attribute is specified, then the data is initially scrolled to the bottom.
webtracker
Adds a WebTracker toolbar to the pane. The user can use this toolbar to surf the web.

It is strongly suggested that authors use standard, simple names such as “book”, “chart”, and “map” for persistent panes. This is because Pueblo remembers where these panes are positioned by the user. For example, if the user moves and sizes a persistent pane named 'book' , closes the pane, and later reopens the pane, it will be positioned where the user last placed it. Users appreciate this level of control over the interface.

If this attribute is not specified, the default is “overlapped”.

The ‘fit’ option

The fit option is very useful for making pages of information appear pleasing on different display devices. The pane is sized as well as possible to fit its displayed contents.

Because HTML wraps text to fit the width of the display window, the results of a fit pane are dependent on the original width of the pane. The HTML is wrapped to this width, and the pane is then sized to the result. Because of this, it is desirable to specify a WIDTH value.

Because the fit option is designed for use with static data, it generally should be used with the nonsizeable option. You can do this, but the results are unpredictable.

Here is an example of using the fit option:

<xch_pane action=open name=dialog panetitle="Registration Form"
href="http://www.chaco.com/reg_dialog.html" width=640 midwidth=200 options=”floating fit nonsizeable”>

Examples

The following code opens a HTML file into a normal pane:

<xch_pane action=open name=book panetitle="The book of the Realm"
href="http://www.chaco.com/example.html">

This code will close the floating pane opened by the previous example:

<xch_pane action=close name=book>

The following code opens a bitmap file into a floating pane. The pane is nonsizeable, and is sized to fit the image. In addition, the pane is persistent, so that if it is created a second time, it will appear where it was last placed by the user:

<xch_pane action=open name=map xch_panetitle="Map of the City"
href="http://www.chaco.com/map.jpg"
options="floating persistent fit nonsizeable"
vspace=5 hspace=5>

The following code creates a new internal "banner" pane at the bottom of the user's Pueblo window. The pane is automatically sized vertically to fit its contents.

<xch_pane action=redirect name=mybanner options="internal fit" align=bottom>

After the above HTML is seen by Pueblo, future HTML goes into the new pane (which is named "mybanner"). So, if we then send the following text, it will appear in the internal banner pane:

You can <a xch_cmd=look xch_hint="Look around">look</a>.

To redirect HTML output from the world back to where it was before we did the initial "mybanner" redirection, issue this HTML:

<xch_pane action=redirect name=_previous>

In the case of redirected panes created with the "fit" option, the pane is resized to fit when text is redirected OUT of the pane, so this last step causes the pane to resize.

To redirect text back into the pane, issue this HTML:

<xch_pane action=redirect name=mybanner>

(Note that you could specify the options and alignment parameters just as you did when you created the pane. If the named pane already exists, those parameters are ignored.)

To clear the existing text in the pane, send this HTML:

<xch_page clear=text>

Then put new HTML in the pane:

You can also go <a xch_cmd=out xch_hint="Go out">out</a>.

And redirect HTML back to where it was before:

<xch_pane action=redirect name=_previous>

Note that when using redirect, it is usually better to redirect back to _previous instead of _top, in case output was somewhere other than _top when you did your redirect.

Also see

Creating and using HTML dialogs

Data sent from world:	Behavior:
This is the main pane.	Initially, all output goes to the Pueblo log window. This string will appear in the log window.
<xch_pane action=redirect name=mylog>	This opens a new window with the internal name “mylog” and begins sending all stream data to that window.
This is my private log pane.	This data will appear in the new pane named “mylog”.
<xch_pane action=redirect name=book>	This opens a new window with the internal name “book” and begins sending all stream data to that window.
This is my book pane.	This data will appear in the new pane named “book”.
<xch_pane action=redirect name=_previous>	This switches redirection to the previous pane in the stack. In this case, the previous pane is named “mylog”.
I really like my private log pane. It is my friend!	This data will appear in the new pane named “mylog”. If “mylog” was closed by the user after it was created, then the data is ignored and not displayed. (Note that the main Pueblo log window can never be closed by the user.)
<xch_pane action=redirect name=_top>	This switches output back to the Pueblo log window and removes all windows from the stack.
Back in the main pane!	This string will appear in the main log window.

open	Opens a pane. The HTML string must include a href attribute indicating what should be displayed in the pane. If the action attribute is not specified, this is the default.
close	Closes a pane. If this value is used, the author must also specify a name attribute. (All other attributes to this command are ignored.)
redirect	Causes all stream data following this element to be sent to the TARGET pane. If the target pane does not exist and the OPTIONS=”existing” is specified, then the redirected text is discarded until the redirection target is changed. If you specify the HREF attribute with this action, the data stream is *not* redirected and will continue to be processed in the current pane. The document specified by the URL will be appended to the existing pane. If the pane doesn’t exist then a new pane will be opened (unless OPTIONS=”existing” is specified.)

_blank	When used with action=open and options=browser or options=webtracker, this causes an empty, unnamed pane to be created. This is the default value when this attribute is not specified. The following restrictions on this name apply: 1) This can be used only with action=open. 2) If options=browser is specified then the configured web browser is opened 3) If options=webtracker is specified then WebTracker is opened. 4) If options=browser or options=webtracker is not specified then a new nameless pane is opened only if HREF attribute is set.
_previous	When used with action=redirect, causes redirection to pass to the previous pane that received redirection.
_top	Causes redirection to be eliminated, so that data coming across goes to the main pane of the set. This does nothing when action=close.

overlapped	Creates a pane that is a peer of the main application. The pane may be moved to the back of the application by the user. May not be used with the floating, internal, or docking options.
floating	Creates a pane that floats above all non-floating pueblo client windows. May not be used with the overlapped, internal, or docking options.
internal	Causes an internal pane to be created. The pane is created at the top of the window unless the align=”bottom” option is specified. May not be used with the overlapped, floating, or docking options.
browser	Opens the user’s generic browser application. This may be WebTracker or another browser such as Netscape. Note that if this option is used, the sizing and alignment options will be ignored, as the browser may be a separate application.

nonsizeable	Creates a pane that may not be resized by the user.
noclose	Creates a pane that may not be closed by the user. This option is ignored for panes created as unnamed.
small_title	Creates a pane that has a smaller caption. These panes take slightly less space than normal panes.
fit	This option causes the pane to size to fit the contents of the pane. For more information on this option, see below.
persistent	Causes the pane to remember its last position and size.
force	Forces the location and size specified. A pane created with this option will not use the stored location by default. This option is only meaningful for persistent’ panes.
viewbottom	Causes the pane to scroll to the bottom whenever new data is appended. If an HREF attribute is specified, then the data is initially scrolled to the bottom.
webtracker	Adds a WebTracker toolbar to the pane. The user can use this toolbar to surf the web.