May 8, 1995
Inherits from GadgetWindow Inherits from InfoTopic
Info windows display help information for scenes and windows. Whenever you tap on the help stamp in the upper left of a scene, the system displays an info window containing help for the scene. You'll need to know about info windows so you can provide help for your package scenes.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Instantiate: rarely Subclass: rarely Call its methods:rarely
If you're not likely to instantiate, subclass, or call the methods of class InfoWindow, why should you care? Because every time you need to provide help text for scenes or windows in your package, you'll need an info window to display the help. Most of the time you won't need to worry, because you'll be using the default system info window. Sometimes you'll want to customize the window.
Every scene and most titled windows in Magic Cap have a circled question mark in the upper left corner. The question mark looks like this:
When you tap on the question mark, the system displays the help info for the scene or window.
The system gets the help info by calling Info on the scene or window. Info is a method of class Object. If the object is a system object, Info checks if the object is in the system list of objects with help. If the object is a package object, it checks if it's in the package list of objects with help. Some classes, like class ModalScene and class AttributeWindow override Info to implement their own ways of storing help information.
Class SoftwarePackage provides a framework that lets you provide help for most of your package objects. To add help information to your package, create two object lists: a listing of the scenes and windows you want to provide help for, and a corresponding list of help objects. Put the list of objects with help into the entry9 field of your software package object, and the list of help objects into entry10.
Here's a possibly familiar example of a package that uses help text for its scene and several of its windows:
Instance SoftwarePackage 'Scramble' 1;
// fields elided for brevity
entry9: (ObjectList 'Objects With Help' 37);
entry10: (ObjectList 'Help On Objects' 38);
// more fields elided
End Instance;
Instance ObjectList 'Objects With Help' 37;
length: 6;
entry1: (ScrambleScene 'Scramble' 4);
entry2: (GadgetWindow 'words tried' 32);
entry3: (ButtonedWindow 'high scores' 33);
entry4: (GadgetWindow 'options' 72);
entry5: (GadgetWindow 'players' 71);
entry6: (GadgetWindow 'words tried' 102);
End Instance;
Instance ObjectList 'Help On Objects' 38;
length: 6;
entry1: (TextField 39);
entry2: (Text 138);
entry3: (Text 139);
entry4: (Text 140);
entry5: (Text 141);
entry6: (Text 160);
End Instance;
Each item in the `Objects With Help' list should match with an item in the `Help On Objects' list. The GadgetWindow `players' has the help text found in Text 141. When the user taps on the circled question mark in the title bar of the players window, the system displays an info window containing that text.
Help objects must either be text objects or viewable objects. Most of your help items will be text objects containing your help text. The system fills in the text fields of the default info window with your help text.
The framework for help given by the software package object lists lets you associate only one help topic with each scene or window. It doesn't work when you're writing help for a modal scene or for any other kind of viewable that can contain different groups of objects. Classes like this often override Info to get at custom help stored in an info field.
If you're writing a custom class that needs several different help topics for one object, you should do something similar. Mix in class InfoTopic with your class. Class InfoTopic provides you with an info field and a corresponding Info attribute. You should override the getter for Info to return the appropriate help object for each situation.
Class ModalScene doesn't inherit from class InfoTopic. Instead, it has a custom modalInfoList field. It overrides Info this way:
Method ObjectID
ModalScene_Info(ObjectID self)
{
ObjectID stepInfo, modalInfoList = Field(self, modalInfoList);
/* check to see if this modal scene has custom help */
if (modalInfoList != nilObject)
{
/* use the view mode as an index into the help object
list */
stepInfo = At(modalInfoList, ViewMode(self));
if (stepInfo != nilObject)
return stepInfo;
}
/* if we haven't found custom help, use the default help
framework */
return InheritedInfo(self);
}
Your override of the Info getter might look similar.
Sometimes you'll want more than just help text. You might want to add stamps or buttons. The info window for the desk scene, for example, uses three text fields with different fonts, two stamps, and a button.
To add other viewable objects to a help window, fill in the help slot with the first viewable you want displayed in the window. That viewable should point to the next item to display, and the view chain should end (as usual) with nilObject in the last item's next field. When the info window is displayed, the system sets its first subview to be the viewable in the `Help On Objects' list.
If you're using your own text fields, point each field to the text object containing the text to display in that field. The system won't fill in the fields for you if you're providing your own viewables for the info window.
Class InfoWindow defines the following methods:
| Method | Description |
|---|---|
| PopulateTextFields | Fill in the text fields with the text of the info topic |
| ClearInfoTopic | Hide the info window and set its topic to nilObject |
| HideInfoTopic | Hide the info window if it's displaying the given topic |
| ShowInfoTopic | Show the given topic |
| ShowOrHideInfoTopic | Toggle the visibility of the window displaying the given topic |
| SetInfoTopic | Do the dirty work of setting up an info topic |
| Changing basic window behavior | |
| AboutToHide | Overridden to reset info topic to its ROM state to avoid permanent shadowing |
| CanAccept | Overridden to not let the TouchTool move objects inside the info window (Move tool can) |
| ConstrainToolTarget | Overridden to send all touches in the window to the window itself, not to any subviews |
| TouchTarget | Overridden to give window subviews a chance to handle the touch, then close the window; if the touch isn't in a subview, pass the touch input to Touch |
| Tap | Overridden to hide this window if it has no title bar and it's tapped with a normal tool (otherwise inherited method handles tap) |
| Touch | Overridden to hide this window if it has no title bar and it's tapped with a normal tool (otherwise the inherited method handles the touch) |
| ZoomFromWhere | zoom scene info from scene name |
Class InfoWindow defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from SingleLinkable | ||
| next | Object | Next item in view list |
| Inherited from Linkable | ||
| previous | Object | Previous item in view list |
| Inherited from Viewable | ||
| superview | Viewable | Container for this object |
| subview | Viewable | Object contained by this object |
| relativeOrigin | Dot | Origin relative to superview |
| contentSize | Dot | Size of content rectangle |
| viewFlags | Flags | Property settings |
| labelStyle | TextStyle | Text style of object's label |
| color | Color | Color of object's content |
| shadow | Shadow | Shadow drawn with object |
| sound | Sound | Sound associated with object |
| Inherited from HasBorder | ||
| border | Border | Framed border drawn around object |
| inherited from Window | ||
| windowFlags | Flags | Stores various boolean attributes of the window |
| inherited from TitledWindow | ||
| titleColor | Unsigned | RGB value used to fill in the window's title box |
| titleHeight | Micron | Height of the title box |
| dependents | ObjectList | List of windows used by HasDependent |
| inherited from BalloonSpout | ||
| balloonDot | Dot | The spot the balloon spouts from (ignored by gadget windows) |
| inherited from GadgetWindow | ||
| target | Object | Used by the Target attribute |
| defined by InfoWindow | ||
| currentTopic | Object | The current topic with information being displayed |
| infoFields | Object | A list of fields contained in this info window |
You'll only rarely create your own info windows. Instead, you'll most often use the one already defined by the system, iInfoWindow. Here's the object definition for iInfoWindow:
Instance InfoWindow 'Information' 295; // 84 bytes
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <3.0,-148.0>;
contentSize: <336.0,6.0>;
viewFlags: 0x50004000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: -1;
shadow: iShadowGray8;
sound: nilObject;
border: {120,76}; // gray border
windowFlags: 0x00000041;
titleColor: 0xFF333333;
titleHeight: <0.0>;
dependents: nilObject;
balloonDot: <0.0,0.0>; // to prevent shadowing
target: nilObject;
info: iDefaultInfoList;
currentTopic: nilObject; // to prevent shadowing
infoFields: (TextField 712);
End Instance;
// This field is for the topic of the info text
Instance TextField 712;
next: (TextField 1024);
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <-14.0,-32.5>;
contentSize: <308.0,26.0>;
viewFlags: 0x10019000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: -1;
shadow: nilObject;
sound: nilObject;
border: nilObject;
fieldFlags: 0x80000001;
dataStore: nilObject;
baseStyle: iBook14;
End Instance;
// This field is for the informational text.
Instance TextField 1024;
next: nilObject;
previous: (TextField 712);
superview: nilObject;
subview: nilObject;
relativeOrigin: <-1.0,9.5>;
contentSize: <334.0,62.0>;
viewFlags: 0x10019000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: -1;
shadow: nilObject;
sound: nilObject;
border: nilObject;
fieldFlags: 0x80000000;
dataStore: nilObject;
baseStyle: iBook12;
End Instance;
If you don't provide your own text fields for the info window, the system will use the two above to display your text. You should use one text object to contain all your help text. The first text field displays the first line of your help text in a large font, so the first line of your help text should be the title of your help topic. The rest of your text goes into the second text field.
operation AboutToHide(); Call: rarely Override: rarely
Class InfoWindow overrides AboutToHide to reset the info window to its original state to prevent it from being shadowed in memory. AboutToHide makes two assumptions about the ROM state of an info window:
Your info window objects should set its fields this way to avoid being shadowed because of the assumptions in AboutToHide.
operation ClearInfoTopic(), safe; Call: sometimes Override: rarely
Call ClearInfoTopic to hide an info window and clear its topic. ClearInfoTopic calls Hide, then sets the info topic of the window to nilObject.
operation HideInfoTopic(newTopic: Object), safe; Call: sometimes Override: rarely
Call HideInfoTopic to hide the info window if it's displaying the given topic. The newTopic parameter is the topic to hide. If the window isn't displaying that topic, HideInfoTopic won't hide it. If the topic matches, HideInfoTopic calls Hide on the window.
operation PopulateTextFields(viewList: Object; infoText: Object); Call: rarely Override: sometimes
The system calls PopulateTextFields from the method SetInfoTopic when it's setting up an info window for display. PopulateTextFields fills in the text fields inside the info window with the info text.
The viewList parameter is the first item in the subview chain of the info window. PopulateTextFields steps through the chain and fills in each text field in the chain with a line of text. The text comes from the infoText parameter. Each line of text goes into a separate text field. The last text field in the chain gets all text left over.
operation SetInfoTopic(newTopic: Object); Call: rarely Override: rarely
The system calls SetInfoTopic to set up a new topic for display. The newTopic parameter is the topic to be displayed. SetInfoTopic does the work of making any new viewables subviews of the info window. It also calls PopulateTextFields to fill in any text fields inside the info window with help text.
You'll call SetInfoTopic yourself only rarely. You'll call ShowInfoTopic instead, which calls SetInfoTopic for you.
operation ShowInfoTopic(newTopic: Object), safe; Call: sometimes Override: rarely
Call ShowInfoTopic to show the info window with the given topic. The newTopic parameter is the topic to display.
ShowInfoTopic hides the window, calls SetInfoTopic to set the topic to the new topic, and then shows the window. ShowInfoTopic doesn't check the topic to see if it's different from the currently displayed topic.
operation ShowOrHideInfoTopic(newTopic: Object), safe, common; Call: sometimes Override: rarely
Call ShowOrHideInfoTopic to toggle the visibility of the given info topic. The newTopic parameter is the topic to toggle.
ShowOrHideInfoWindow checks to see if the topic passed in newTopic is the current topic of the info window. If it is, and the window is on-screen, ShowOrHideInfoWindow hides the window. If the topic isn't the current topic or the given window isn't on-screen, it calls ShowInfoTopic to display the topic.