inherits from ChoiceBox
Image choice boxes are choice boxes that display images to represent their choices instead of text. They add two other twists to the basic choice box: they can filter their list items to remove items not of a certain class, and they can construct lists of attributes from a single object and use those lists as their choice lists.
Instantiate: sometimes Subclass: sometimes Call its methods: rarely
You'll rarely need to call the methods of class ImageChoiceBox. Usually you'll put image choice boxes into your object definition files, and rely on the system to call methods when needed. You might want to subclass ImageChoiceBox to implement your own kind of filtering. If you do so, you might override the methods FilterChoices and SetChoices.
Class ImageChoiceBox defines the following methods
| Method | Description |
|---|---|
| FilterChoices | Filters the choice list based on the criteria in the Filter attribute |
| AboutToHide | Overridden to stop observing the source |
| AboutToShow | Overridden to sync the choice list with the source object, show or hide the empty message as appropriate, and begin observing the list source |
| CalcBoundsBox | Overridden to account for the image bounds |
| CalcInsidePart | Overridden to use the part code returned by InsideImage, if any; otherwise delegates to Viewable |
| Draw | Overridden to draw the choice box to reflect its current state |
| DrawControlMechanism | Overridden to delegate to Meter to draw the left and right arrows; also draws the light gray background between the ends of the box |
| Image | Overridden to figure out which image to return, the current choice list item or its image |
| Notice | Overridden to synch the choice list with its source object when the source object changes |
| SetLevel | Overridden to handle changing the choice box's bounds when the displayed image size changes |
| SetChoices | Overridden to call FilterChoices if necessary |
| TextFromValue | Overridden to return nilObject if the value is greater than the size of the choice list; otherwise calls inherited |
| UpdateChoices | Overridden to show or hide the empty message as appropriate |
Class ImageChoiceBox 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 |
| 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 | Unsigned | Color of object's content |
| altColor | Unsigned | Alternative color for object |
| shadow | Shadow | Shadow drawn with object |
| sound | Sound | Sound associated with object |
| Inherited from HasBorder | ||
| border | Border | Frame drawn around control |
| Inherited from Control | ||
| image | Image | Image used to draw control |
| textStyle | TextStyle | Text style used for control's label |
| controlFlags | Unsigned | Various settings for control |
| level | Fixed | Current setting of control |
| min | Fixed | Minimum setting allowed for control |
| max | Fixed | Maximum setting allowed for control |
| target | Object | Object watched and controlled by control |
| targetAttribute | Unsigned | Selected attribute of watched object |
| Inherited from Meter | ||
| upDownImages | Object | The image used for changing the setting; a small right arrow by default |
| Inherited from ChoiceBox | ||
| choices | Object | The list of available choices |
| choiceFlags | Flags | Various settings for the choice box |
| Defined by ImageChoiceBox | ||
| emptyMessage | Viewable | Used by the EmptyMessage attribute |
| source | Object | Object that determines, along with sourceAttribute, the choice list |
| sourceAttribute | Unsigned | Attribute number used to get choice list for choice box from source |
| filter | Unsigned | Used by the Filter attribute |
The source field can contain either an object list or a single item. In most cases, it will be just a list of items the user can choose from. Image choices boxes allow you to do two kinds of processing on this list, however, using the sourceAttribute and filter fields.
If your choice box should display a particular attribute of the source object, fill in the sourceAttribute field with the appropriate attribute number. Thesystem will call Attribute on the item. The list of the results is then used as the choice list in the choice box. This is only meaningful for attributes that are object lists.
If the source attribute is zero, the choice list for choice box is the source object itself. The source field must point to an object list.
If your source list might contain extraneous objects that shouldn't appear int he list, you can filter the list by class. Fill in the filter field with the class number that all items in your final list should implement.
Here's an image choice box that doesn't filter its choice list:
Instance ImageChoiceBox 'view:' 5154;
next: (SimpleActionButton 'storage map' 5155);
previous: nilObject;
superview: (ViewStorageWindow 'View storage map' 5153);
subview: nilObject;
relativeOrigin: <17.50,-48.0>;
contentSize: <157.0,30.0>;
viewFlags: 0x101B1000;
labelStyle: iBook12Bold;
color: 0xFF000000;
altColor: 0xFF333333;
shadow: nilObject;
sound: iTouchSound;
border: nilObject;
image: iTeletouch;
textStyle: iBook14;
controlFlags: 0x35008100;
level: 1.0;
min: 1.0;
max: 1.0;
target: (ViewStorageWindow 'View storage map' 5153);
targetAttribute: operation_ContainerDevice;
upDownImages: iChoiceBoxRightArrow;
choices: (ObjectList 5156);
choiceFlags: 0x08800000;
emptyMessage: nilObject;
source: nilObject;
sourceAttribute: 0;
filter: 0;
End Instance;
The choice list for this choice box is the object list in the choices field. This list isn't massaged or altered at all before it's used in the box. The source, sourceAttribute, and filter fields aren't used at all.
Here's an image choice box that uses a filter:
Instance ImageChoiceBox 8590;
next: (TextField 11292);
previous: (TextField 8595);
superview: (PeoplePhonePicker 'Choose a name:' 8583);
subview: nilObject;
relativeOrigin: <93.0,-76.0>;
contentSize: <110.0,24.0>;
viewFlags: 0x10081000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: 0xFF333333;
shadow: nilObject;
sound: iTouchSound;
border: nilObject;
image: nilObject;
textStyle: iBook12Bold;
controlFlags: 0x35008500;
level: 1.0;
min: 1.0;
max: 2.0;
target: (PeoplePhonePicker 'Choose a name:' 8583);
targetAttribute: operation_PhoneLabel;
upDownImages: iChoiceBoxRightArrow;
choices: (ObjectList 8591); // buffer of filtered choices
choiceFlags: 0x08800000;
emptyMessage: (TextField 11292);
source: iCurrentContact;
sourceAttribute: operation_Addresses;
filter: 367; // PhoneLabel_
End Instance;
This choice box starts with just one address card, the current contact, and constructs a choice list from it. First, it gets a list of all addresses on the card, using the Addresses attribute of the card.Then it filters the list of addresses for phone labels and throws out all the rest. The filter field contains the class number for class PhoneLabel.
Class ImageChoiceBox defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| EmptyMessage | Viewable | A viewable (typically a text field) that is made visible and brought to the front when choice list is empty (can be nilObject) |
| Filter | Unsigned | A class number; used to weed out all items that don't implement this class number |
attribute Filter: Unsigned, safe; Call: sometimes Override: sometimes
The Filter attribute is the interface to the filter field. The filter must be either a class number or 0. If the filter is a non-zero class number, FilterChoices removes from the choice list all items that do not implement this class number. If the filter is 0, the choice list isn't weeded.
You might override Filter if you want to weed out items from the source list according to different criteria. If you do so, you might also override FilterChoices or SetChoices as well.
operation FilterChoices(newChoices: Object; filter: Unsigned); Call: sometimes Override: sometimes
The systems calls FilterChoices from SetChoices while setting up the choice box and synchronizing it with its source list. FilterChoices removes extraneous items from the choice list. FilterChoices is only called if the Filter attribute isn't zero.
FilterChoices implements the behavior described under Filter. It starts with the list in the newChoices parameter and constructs a new version of the choices list from it. The new list contains only the items in newChoices that implement the class number in the Filter attribute.
The list pointed to in the choices field of the choice box object will be changed by FilterChoices.
You might override FilterChoices if you need to do a different kind of filtering on choice lists for your custom image choicel ists.
overrides Draw Call: sometimes Override: sometimes
The system calls Draw to draw a viewable on the screen. Class ImageChoiceBox overrides Draw to draw the image at the center of the choice box. ImageChoiceBox_Draw also draws nothing at all if the choice list contains no choices. It doesn't draw the box's control mechanism (the left and right arrows), if there's only one choice in the list.
overrides Image Call: sometimes Override: sometimes
The system calls Image to get an image to use to represent an object. Class ImageChoiceBox overrides Image to return an image representing its current choice.
If the item at the current level in the choice list is an image, Image just returns that. Otherwise it calls Image on the current item.
overrides SetChoices Call: rarely Override: rarely