TOOLBOOKDEVELOPER.COM

Pop Text Widget User's Guide

It's

Go to User Guide Home

PopText Widget - About the Widget

Developed for:

Click2Learn ToolBook Instructor version 8.5 or higher

Works in:

Native, Neuron, and DHTML ToolBook Projects

Type of Tool:

Catalog Object

Installation

When you download the program, it will self extract into your Program Files directory into a folder for NirvanaBound\PopText##\. At the end of the extraction process it will run a utility (written in ToolBook :-) to find your Instructor file and will install the Widget into your catalog folder.The next time you open ToolBook Use the Customize Catalog feature to import this new PopText category.

How to Use the Widget

Please note that the following details are quite voluminous, this not a refection on the easy of use of this tool, however, it will demonstrate the depth of functionally. It is truly very simple to use when simplicity is all that you need but it has the ability to work, control and be controlled in very complex interactive programs.

1.

Open your ToolBook project and drag the PopText Widget from the Catalog to the page of your project.

2.

After the PopText has been added to your page, the extended properties for the Widget will pop-up.

What are the options:

Properties Help button. When click this will show a PopText Widget. Yes that's right, I have used the Widget inside of the Widgets' (EPE) Extended Properties Editor:-) So whilst in the EPE you have access to the help on options.

PopText Methods. When click this will show a ToolBook viewer which also has a PopText Widget which describes the Methods that you can execute and how to execute them.

Enter Audio File name at reader. (

Number of PopText items: This field displays the number of PopText items.

Current PopText item: This field displays the number current PopText item number.

Default PopText item: This field is the default PopText item to be displayed OnLoad page. If 0 then the last viewed item will not change when you re-visit the page.

Add PopText items: Enter the number of PopText items that you wish to add.
      Add After Current: Indicate that you wish to add the items after the current item.
      Add Before Current: Indicate that you wish to add the items after the current item.

Delete PopText items: Enter a list of PopText items that you wish to delete. Format: 1,2,5-10,15,18

Include Navigation buttons: If not checked then the Navigation buttons will be hidden, you may wish to create hotwords with Actions for the navigation.

Include Page of Pages: If checked this will display the Page of Pages eg. 2 of 20

Include Close Button: If checked this will display the Close button. You may choose to display the PopText Widget as a PopUp. eg. Click here for additional information.

Always Visible: If checked the the PopText will be visible at reader and OnLoad page.

Dragging at Reader Level: If checked then the PopText Widget can be dragged at reader level. This feature is will not work in DHTML

Send PopText Triggers: If checked then the PopText Widget will send a Action System User event to the current page. The parameter value will be set to one of the following:
      PopTextShowPopText - This Trigger is sent when the PopText Widget is shown.
      PopTextHidePopText - This Trigger is sent when the PopText Widget is hidden.
      PopTextShow# - where # is the PopText item number being shown. eg. PopTextShow1 or PopTextShow3
 

Colors. When click this will show a ToolBook viewer which will allow you to change the colors and font of your PopText Widget. This also includes a PopText Widget which is used to show the changes as you select various color comminations, additionally it describes what you need to do if the default PopText buttons do not suit your choice of colors.

This dialog is reasonably intuitive as we have all seen the standard ToolBook color selectors and the font popup is also a standard ToolBook dialog, what is important to note is that the font will be applied to all of the PopText items and will not affect the color of Hotwords or the font + color of text that you have applied special formatting. i.e. It will just change the properties of the field!

Apply: This button will update the selected PopText in the mainWindow. If you do not click this button then all of the color + font changes will be lost.

Close: This will close the Colors dialog.

The small PopText objects on the right side will allow you to select predefined colors, simply click on them, once selected you can further modify the colors before clicking on the Apply button. The first two will "Revert to original styles..." and "Original Nirvana Bound..." respectively.

Revert to original styles of the current PopText Widget: When the dialog opens this item will change to reflect the colors of the current PopText Widget in the mainWindow. If you have made some changes and then clicked on the Apply button and now find that you don't like what you see you can click on this item to revert back to the original. Don't forget to click the Apply button again if this is the case:-)

Original Nirvana Bound PopText styles: This has the same functionality as the above except it will return your PopText Widget to the same as if you just added a new PopText Widget from the catalog.

Note how the first two are the same color, this is because the current PopText Widget in the mainWindow is the same as the default:-)

3.

The PopText Widget is quite intuitive and you should not need to supply user instructions, however, as you are developing your program you need to enter text and you will need to navigate from one PopText item to another - right?

The PopText navigation buttons (and the Close button) will work at author level:-) All that you need to do is hold either the <Ctrl> or <Shift> key down and single click on the appropriate button, be careful when clicking, ensure that you click slowly because you may actually send a double button click. This not a problem, however, the <Ctrl>+double click will edit the OpenScript (of the selected object) and the <Shift>+double click will open the properties dialog (of the selected object), note that the selected object will be the PopText Widget. Both <Ctrl>+<Shift> will work too and a double click will open the Extended Properties Editor. BTW these double click functions are standard ToolBook features and will work with any object.

To enter text for a give PopText item you need to double click on the field until the text insertion point appears in the field. This is a real pain as the actual field is in a group which is also in a group which is in the PopText group:-( This means that you need to double click 4 times!! If you hold either the <Ctrl> or <Shift> key down and then single click then the PopText Widget will select the field, now release the <Ctrl> or <Shift> and do just one double click.
Hint: If you turn on "Show right-click menus at Reader level" and at reader you right click on the field, unselect "Activate Scripts" then you can enter the text at reader level. Don't forget to repeat this process and ensure that the "Activate Scripts" is checked before you deploy your program.

4.

Give it a whirl! Hit F3 and go into reader mode. If experience and problems please consult the Troubleshooting Guide.


Special Features of the PopText Widget

1.

The PopText Widget does not use any global variables and you can have more than one PopText on a given page.

2.

This widget uses Action Methods and you can execute these Methods from other ToolBook objects. To read about how to use Methods click here.

The following is a list of the PopText methods that you can execute:

 

Name

 

Description

1

gotoFirstPopText

 

This method will navigate to the first PopText item.

2

gotoLastPopText

 

This method will navigate to the last PopText item.

3

gotoNextPopText

 

This method will navigate to the next PopText item.

4

gotoPopTextDefault

 

If you have defined a default PopText item then this method will go to the default PopText item.

5

gotoPopTextNum

 

This method will navigate to the PopText item number using the parameter PopTextNum.

6

gotoPreviousPopText

 

This method will navigate to the previous PopText item.

7

hidePopText

 

This method will hide the PopText.

8

showPopText

 

This method will hide the PopText, this method is called from the Close button.

The following is a list of the PopText methods that you should not execute:

 

Name

 

Description

1

checkPopTextNavGrp

  This method will enable/disable the appropriate navigation buttons.

2

getAlwaysVisible

 

This method will return true if the PopText is to visible. This is used to hide/show the PopText On load page.

3

getCurrPopTextNum

  This method will get the number in the CurrentPopTextNum field which will be the current PopText item.

4

getCurrPopTextNum

 

This method will get the number in the CurrentPopTextNum field which will be the current PopText item.

5

getMaxPopText

 

This method will get the number in the MaxPopTextNum field which will be the last PopText item.

6

getSendTriggers

 

This method will return true if the PopText will send triggers to the current page. Also See: sendPopTextTriggers

7

hideAllPopTexts

  This method will hide all PopText items.

8

sendPopTextTriggers

 

If getSendTriggers returns true then the PopText will send a User event to the current page. The following Triggers are sent as the value parameter:
     PopTextShow# where # is the PopText item number
     about to be shown. eg.
         PopTextShow3
     PopTextHidePopText sent before the PopText is hidden.
     PopTextShowPopText sent before the PopText is shown.

9 setCurrPopTextNum   This method will set the CurrentPopTextNum field to the number passed in the parameter PopTextNum.
3. The PopText Widget is a complex grouping of ToolBook objects. This allows us to insert other ToolBook objects inside of the Widget. An excellent example of this would be to include graphics for one or more PopText item/s.

The following is the best way to do this:

Step Description
1  Add the graphic/s to the page as separate objects. I prefer to use buttons and add the graphics as a resource.
2 Ensure that they are the correct size and move them away from the PopText.
3 For each graphic:
4    go to the correct PopText item
5    select the correct graphic (added in point 1), bring it to the front (<ctrl>+<shift>+F)
6    move it to the correct location on top of the PopText item.
7    cut it - <Ctrl>+X
8    hold the <ctrl> or <shift> key down and click (one click only) in the middle
   of the PopText Widget, this will select the text field for the current PopText
   item (which is in a group:-)
9    do <ctrl>V (paste)
10 Repeat starting from step 4 above

Couple of things to note:

Note Description
1 If you resize the PopText then all objects will resize so it's a good idea to do steps 4 to 6 in isolation first. This way you know that they all will fit OK without having to go back to each PopText item to check if they still look OK after resizing.
2 You can do the above with the graphic outside the visible bounds of the PopText Widget
3 You could apply show/hide Actions by turning the Triggers on, but it's a lot easier to do the above:-)
4 Change the word "graphic" to any ToolBook object:-)
   i.e. Buttons, fields, lines, groups - ANY ToolBook object/s
   e.g. You may need to show a table, just create the table from a group of fields.
          or:
          How about adding a MC question??? - Yep, it will work:-)

 

4. As mentioned above the PopText is a complex grouping of objects there are 24 objects in a PopText Widget with just 2 PopText items.
Starting from the bottom:

Objects Description
4 The base consists of three IrregularPolygons which are grouped and the "Export the group as a graphic" is checked, this means we only have one object exported.
7 Each PopText item consists of a group which contains a field and a 1 x 1 pixel line, we need the line or else we can't create a group, the reason for the group is to allow you to add objects to a PopText item. The PopText items are in turn grouped which means we need a minimum of two PopText items.
5 The navigation consists of four buttons which are grouped
4 The "Page of Pages" consists of three fields ("Page", "of" and "Pages") which are also grouped. The "Page" is user to determine the current PopText item to control previous and next; and the "Pages" is for last items
3 The Close button, default PopText item field and the options field. The last two fields are hidden.
1 Finally the actual PopText Widget, grouping all of the above.

 


PopText Widget Limitations

1. If you change the base color the the shading on the navigation and close buttons may not suit the new color.
To fix this just change the graphics to a more suitable color.
2. Resizing when there are objects inserted in with the PopText items or in the PopText group.
If you resize after adding objects you may need to readjust the size of the insert objects as they will resize along with the PopText Widget.
3. Export and the number of objects in the PopText Widget.

Frequently Asked Questions

How many PopText items can I have?
There is no limit to the number of PopText items other than the number of objects that a given page may hold.

How many PopText Widgets can I have on a single page?
As with the number of PopText items, there is no limit to the number of PopText Widgets on a given page.

How do I add hotwords and link to PopText items from a PopText item?
The text you see in a PopText item is in a standard ToolBook field, so anything you can do with a field you can do with a PopText item. Simply select the text and select the Text menu and then Create hotword or do <Ctrl>+H, I like to name my hotwords, all that you now need to do is add an Action to the hotword and the Action will be in the On click... event and will typically execute the Method gotoPopTextNum where you indicate the item number.

How do I insert graphics or other objects for a give PopText item?
Refer to the "Special Features of the PopText Widget" where I discuss include graphics.


Troubleshooting