sub_arctic.lib
Class manager

java.lang.Object
  |
  +--sub_arctic.lib.manager

public class manager

extends java.lang.Object

This class provides overall coordination and management functions for the toolkit as well as providing a series of utility functions, and functions that isolate the interface to AWT. This class contains only static members and methods and is never actually instantiated.

Field Summary

protected static java.util.Vector	_all_applets Set of all AWT applets that top_level interactors are hosted by.
protected static java.util.Vector	_all_awt_components Set of all AWT components that top_level interactors are hosted by.
protected static java.awt.image.ImageObserver	_an_observer An ImageObserver object that does nothing.
protected static java.awt.Image	_broken An image that we provide when a requested image can't be loaded or otherwise has a problem.
protected static loaded_image	_broken_image_icon A loaded_image that we provide when a requested image can't be loaded or otherwise has a problem.
protected static cycle_handler	_cycle_handle_object The current custom constraint handling handling object (if any).
protected static int	_cycle_handling_mechanism The current constraint cycle handling response.
protected static color_pair	_default_color_pair This holds the system's default color pair
protected static java.awt.Toolkit	_default_toolkit Reference to a toolkit object that we can use to create things.
protected static boolean	_enable_debug_print Flag to enable (or disable) printing of debugging messages via debug_print() and/or debug_println().
protected static dispatch_handler	_event_dispatch_handler
protected static int	_event_seq_num Counter for event sequence numbers.
protected static java.util.Hashtable	_extern_constraints_table Lookup table for associating external constraints with interactors.
protected static exception_handler	_handle_object The current custom exception handling object (if any).
protected static int	_handling_mechanism The current exception handling response.
protected static long	_marked_time Timestamp for last call to mark_time()
protected static java.util.Hashtable	_notify_list_table Lookup table for storage of notify lists on behalf of interactors (this is part of the "external" or "heavyweight" constraint system).
protected static java.util.Vector	_policy_list Set of all input dispatch policies.
protected static boolean	_something_is_damaged Flag indicating something somewhere is damaged.
protected static java.util.Vector	_top_level_interactors Set of all top level interactor objects in the system.
protected static int[]	_workaround_table Table of workaround sets.
protected static java.util.Vector	after_dispatch This is a list of dispatch_agents who would like to be informed whenever an event was successfully dispatched.
static animation_agent	animation Animation agent.
static click_track_agent	click_tracker Click tracker.
static event_trace_agent	event_tracer Event trace dispatch agent.
static int	EXCEPTION_CUSTOM Option flag to handle an unexpected exception by sending the "handle_exception()" message to the object previously registered via "handle_exceptions_with()".
static int	EXCEPTION_IGNORE Option flag to ignore unexpected exceptions -- this is generally a very bad idea, think twice before using this.
static int	EXCEPTION_MESSAGE_CRASH Option flag to handle an unexpected exception by printing the exception message to System.err and then exiting.
static int	EXCEPTION_PRINT_MESSAGE Option flag to handle an unexpected exception by printing the exception message to System.err and then continuing.
static int	EXCEPTION_PRINT_STACK Option flag to handle an unexpected exception by printing a stack trace on System.error and then continuing.
static int	EXCEPTION_STACK_CRASH Option flag to handle an unexpected exception by printing a stack trace on System.error and then exiting.
static focus_policy_class	focus_policy Focus input policy.
static grow_drag_focus_agent	grow_drag_focus Grow-drag focus agent.
static grow_press_drag_agent	grow_press_drag Agent that combines press and grow_drag.
static inout_drag_focus_agent	inout_drag_focus Inout drag focus agent.
static inout_press_drag_agent	inout_press_drag Agent for inout_press_dragging.
static mon_focus_policy_class	monitor_focus_policy Monitor focus input policy.
static move_drag_focus_agent	move_drag_focus Move-drag focus agent.
static move_press_drag_agent	move_press_drag Agent that combines press and move_drag.
static navigation_agent	navigation_focus Navigation focus agent.
static point_agent_class	point_agent Agent that handles the pointable protocol for telling when objects are entered or exited.
static positional_policy_class	positional_policy Positional input policy.
static click_agent	press_click_agent Agent for pressable, clickable, and double_clickable.
static raw_focus_agent	raw_focus Raw input event focus dispatch agent.
static raw_focus_agent	raw_monitor Monitor version of raw focus dispatch agent.
static raw_positional_agent	raw_positional Raw input event positional dispatch agent.
static selection_agent_class	selection_agent Agent for maintaining a currently selected set with mouse presses
static simple_drag_focus_agent	simple_drag_focus Simple drag focus agent.
static simple_press_drag_agent	simple_press_drag Agent that combines press and simple_drag .
static snap_drag_agent	snap_drag_focus Snap-drag focus agent.
static text_focus_agent	text_focus Text focus agent.
static int	WA_DYNAMIC Special platform id to support dynamically added workarounds.
static int	WA_IE3 Platform id for workarounds related to MS Internet Explorer 3.x.
static int	WA_JDK1_ALL Platform id for workarounds related to JDK 1.0.x on all machines.
static int	WA_JDK1_MAC Platform id for workarounds related to JDK 1.0.x on the Mac.
static int	WA_JDK1_PC Platform id for workarounds related to JDK 1.0.x on Wintel machines.
static int	WA_JDK1_SUN Platform id for workarounds related to JDK 1.0.x on Sun machines.
static int	WA_MAX_PLATFORM_ID Largest platform id in use
static int	WA_NS3_ALL Platform id for workarounds related to Netscape 3.x on all machines.
static int	WA_NS3_MAC Platform id for workarounds related to Netscape 3.x on the Mac
static int	WA_NS3_PC Platform id for workarounds related to Netscape 3.x on Wintel machines.
static int	WA_NS3_SUN Platform id for workarounds related to Netscape 3.x on Suns
static int	WA_REDUNDANT_MOVES
static int	WA_TRACKER_HANGS
static int	WA_USER1
static int	WA_USER10
static int	WA_USER11
static int	WA_USER12
static int	WA_USER13
static int	WA_USER14
static int	WA_USER15
static int	WA_USER16
static int	WA_USER17
static int	WA_USER18
static int	WA_USER19
static int	WA_USER2
static int	WA_USER20
static int	WA_USER21
static int	WA_USER22
static int	WA_USER23
static int	WA_USER24
static int	WA_USER25
static int	WA_USER26
static int	WA_USER27
static int	WA_USER28
static int	WA_USER29
static int	WA_USER3
static int	WA_USER30
static int	WA_USER31
static int	WA_USER32
static int	WA_USER4
static int	WA_USER5
static int	WA_USER6
static int	WA_USER7
static int	WA_USER8
static int	WA_USER9
static window_agent	window_focus This is the agent for handling the notification of window events.
static work_agent	work This is the agent for handling the work procedures set up for doing multithreaded programming.

Method Summary

static void	activate_workaround(int platform_id, int workaround_id) Activate a specific platform specific workaround.
static void	add_to_after_dispatch_list(dispatch_agent agent) Add an agent to the list of agents interested in the after dispatch hook.
static void	add_to_ood_notify(value_provider for_prov, int for_part, value_consumer notify_obj, int notify_part) Add an element to the notify list being maintained for the given value_provider part.
static void	add_top_level(top_level int_obj) Add a top_level object to the set of active top_level objects.
static java.applet.Applet	an_applet() Return some active AWT applet.
static java.awt.Component	an_awt_component() Return some active AWT component.
static java.awt.image.ImageObserver	an_observer() Return an ImageObserver that does nothing.
static loaded_image	broken_image_icon() Provide a standard "broken image" icon that can be used to substitute for images that couldn't be loaded for some reason or another.
protected static java.awt.Image	build_broken_icon() Build the "broken image" icon from static data.
static cycle_handler	cycle_handle_object() The current custom exception handling object (if any).
static int	cycle_handling_mechanism() The current constraint cycle handling response.
static void	debug_print(java.lang.String str_to_print) Debugging print routine.
static void	debug_println(java.lang.String str_to_print) Debugging print routine.
static color_pair	default_color_pair() This function returns the default color pair for the system. Note: This is now obsolete -- use the style system instead.
static java.awt.Toolkit	default_toolkit() Get a reference the default native toolkit object.
static boolean	dispatch_event(java.awt.AWTEvent evt, top_level top_obj) This method dispatches a single event (that occurred "inside of" the given top level object) to the appropriate interactor object(s) in the interface.
static void	do_redraw(top_level top_obj, drawable surface) This method causes a redraw of the given interactor tree (this is normally called on the basis of a redraw request from AWT).
static void	drop_extern_constraint(value_consumer cons_obj, int cons_part) Remove any association between the given part of a value_consumer and a value_producer.
static void	dump_platform_properties() Helper routine to dump useful system properties to System.out.
protected static boolean	enable_debug_print() Indicate if printing of debugging messages via debug_print() and/or debug_println() is enabled (printing is enabled by default).
static void	establish_extern_constraint(value_consumer cons_obj, int cons_part, value_provider prov_obj, int prov_part) Establish an associative link between the given part of a value_consumer (usually an interactor) and part of a value_provider (usually an external_constraint) that gives it a value.
static dispatch_handler	event_dispatch_handler() Retreive the current event dispatch handler.
static int	event_seq_num() Return the sequence number for the current event.
static provider_part_ref	find_extern_constraint(value_consumer cons_obj, int cons_part) Get the value_provider and part associated with the given value_consumer part.
static java.awt.FontMetrics	get_metrics(java.awt.Font for_font) Get a FontMetrics object for the given font.
static java.util.Vector	get_ood_notify(value_provider for_prov, int for_part) Get the notify list being maintained for the given value_provider part.
static boolean	handle_cycle(interactor in_obj, int part_code) Handle a cycle.
static void	handle_cycles_with(int handling_type) Establish how constraint cycles are handled.
static void	handle_cycles_with(int handling_type, cycle_handler handler) Establish how constraint cycles are handled.
static void	handle_exceptions_with(int handling_type) Establish how unexpected exceptions are handled.
static void	handle_exceptions_with(int handling_type, exception_handler handler) Establish how unexpected exceptions are handled.
static exception_handler	handle_object() The current custom exception handling object (if any).
static void	handle_unexpected_exception(java.lang.Exception except) Handle an unexpected exception that arrived at some part of the toolkit.
static int	handling_mechanism() The current exception handling response.
protected static void	identify_platform_workarounds() Do the detective work to determine which platform we are on and hence which set of platform specific work arounds should be enabled.
static void	install_policy_after(input_policy add, input_policy after) Install a new policy after an existing one (or at the end of the policy list).
static void	install_policy_before(input_policy add, input_policy before) Install a new policy before an existing one (or at the beginning of the policy list).
protected static void	install_standard_policies()
static loaded_image	load_code_image(java.applet.Applet host_ap, java.lang.String image_file_name) Load an image from a location named relative to the location of the code (the .class file) for the given applet.
static loaded_image	load_doc_image(java.applet.Applet host_ap, java.lang.String image_file_name) Load an image from a location named relative to the document that contains the given applet.
static loaded_image	load_image(java.net.URL from_url) Load an image from the given URL.
static void	mark_time() Mark a time for debugging or performance analysis purposes.
static long	marked_time() Timestamp for last call to mark_time()
static boolean	need_workaround(int platform_id, int workaround_id) Determine if a given platform specific workaround (identified by a platform id and workaround id pair) is needed on the platform we are currently running on.
static void	perform_work(work_proc wp, java.lang.Object arg) You can call this method from another thread and it will perform the work represented by the work_proc with the system in a safe synchronization state.
static void	print_stack_trace() Debugging routine to print a trace of the current call stack on on System.err, then return.
static void	print_stack_trace(java.io.PrintStream strm) Debugging routine to print a trace of the current call stack on on the given PrintStream, then return.
static void	register_awt_component(java.awt.Component awt_comp) Indicate that an AWT component that will be hosting a sub_arctic top_level object has been created.
static void	remove_from_after_dispatch_list(dispatch_agent agent) Remove an agent from the list of dispatch_agents which are interested in the after dispatch hook.
static boolean	remove_ood_notify(value_provider for_prov, int for_part, value_consumer notify_obj, int notify_part) Remove an element from the notify list being maintained for the given value_provider part.
static void	remove_top_level(top_level int_obj) Remove a top_level object from the set of active top_level objects.
static void	report_damage(top_level from_obj) Report to the system that a top_level object has recorded some damage that requires it to be redrawn.
static java.lang.String	sec_str(long timestamp) Utility routine to convert a time stamp to a string indicating seconds and milliseconds.
static void	send_dispatch_result_to_handler(dispatch_result dr) Send a dispatch_result to the current dispatch handler, if one exists.
protected static void	set_enable_debug_print(boolean status) Enable (or disable) debugging messages via debug_print() and/or debug_println().
static void	set_event_dispatch_handler(dispatch_handler edh) This function is used to set the dispatch result handler.
static long	since_marked_time() Time since the last call to mark_time()
static boolean	something_is_damaged() Indicate whether there is something in the system that is damaged and needs to be redrawn.
static void	timed_debug_println(java.lang.String str) Debugging print routine to print a string (with newline) with the time corresponding to since_marked_time() appended.
static int	unique_int() Return a positive integer value that is unique among results from this routine (we ignore the fact that this will eventually wrap-around, so if you need one every micro-second, do it yourself with a long).
static void	unregister_awt_component(java.awt.Component awt_comp) Indicate that an AWT component that has been hosting a sub_arctic top_level object is not longer doing so.
static boolean	wait_for_image(java.awt.Image img) Block until the given image is loaded (or there is an error in loading).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_policy_list

protected static java.util.Vector _policy_list

Set of all input dispatch policies.

_something_is_damaged

protected static boolean _something_is_damaged

Flag indicating something somewhere is damaged.

_top_level_interactors

protected static java.util.Vector _top_level_interactors

Set of all top level interactor objects in the system.

_all_awt_components

protected static java.util.Vector _all_awt_components

Set of all AWT components that top_level interactors are hosted by. Note: this list is not synchronized with the list of top level interactors.

_all_applets

protected static java.util.Vector _all_applets

Set of all AWT applets that top_level interactors are hosted by. Note: this list is not synchronized with the list of top level interactors or the list of awt components.

_default_toolkit

protected static java.awt.Toolkit _default_toolkit

Reference to a toolkit object that we can use to create things.

_notify_list_table

protected static java.util.Hashtable _notify_list_table

Lookup table for storage of notify lists on behalf of interactors (this is part of the "external" or "heavyweight" constraint system). This is indexed by provider_part_ref's and contains Vectors of consumer_part_ref's.

_extern_constraints_table

protected static java.util.Hashtable _extern_constraints_table

Lookup table for associating external constraints with interactors. This is indexed by consumer_part_ref's and contains provider_part_ref's.

_event_dispatch_handler

protected static dispatch_handler _event_dispatch_handler

monitor_focus_policy

public static mon_focus_policy_class monitor_focus_policy

Monitor focus input policy. This policy is focus based (it passes inputs to objects which have established themselves as the focus) but is set up to monitor events only, not consume them. This is useful for things like creating new kinds of cursors, where we need to know the position of events, but still want them delivered elsewhere.

event_tracer

public static event_trace_agent event_tracer

Event trace dispatch agent. This agent works under the monitor focus input delivery policy and prints a human readable trace of events as they arrive (for debugging purposes), but does not actually distribute them anywhere. Trace printing is off by default. To start tracing send the message do_trace(true) to this object.

raw_monitor

public static raw_focus_agent raw_monitor

Monitor version of raw focus dispatch agent. This agent works under the monitor focus policy and delivers raw events to requesting objects. This is here primarily as a hook for implementing unusual actions (although a lot of things it might be used for are probably better handled by adding new policies and/or agents, so you might want to consider that before building something with this).

click_tracker

public static click_track_agent click_tracker

Click tracker. This agent allows an object to monitor mouse button state outside its normal domain (to for example realize that the release matching a previous press will never arrive since it was delivered somewhere else). This agent works with click_tracking objects and only delivers input resulting from MOUSE_UP, and MOUSE_DOWN events.

focus_policy

public static focus_policy_class focus_policy

Focus input policy. This policy delivers inputs to objects which have made themselves the focus of various kinds of inputs (rather than, for example positionally -- based on the mouse position at the time of the event).

raw_focus

public static raw_focus_agent raw_focus

Raw input event focus dispatch agent. This agent works under the focus policy and delivers raw events to requesting objects. This is here primarily as a hook for implementing unusual actions (although a lot of things it might be used for are probably better handled by adding new policies and/or agents, so you might want to consider that before building something with this).

simple_drag_focus

public static simple_drag_focus_agent simple_drag_focus

Simple drag focus agent.

move_drag_focus

public static move_drag_focus_agent move_drag_focus

Move-drag focus agent.

grow_drag_focus

public static grow_drag_focus_agent grow_drag_focus

Grow-drag focus agent.

snap_drag_focus

public static snap_drag_agent snap_drag_focus

Snap-drag focus agent.

inout_drag_focus

public static inout_drag_focus_agent inout_drag_focus

Inout drag focus agent.

navigation_focus

public static navigation_agent navigation_focus

Navigation focus agent.

text_focus

public static text_focus_agent text_focus

Text focus agent.

window_focus

public static window_agent window_focus

This is the agent for handling the notification of window events.

work

public static work_agent work

This is the agent for handling the work procedures set up for doing multithreaded programming.

animation

public static animation_agent animation

Animation agent. This agent handles the scheduling of animation events (via its 'transitions' notion to interested interactors. It will deliver these events to any interactor scheduling a transition, independent of other factors such as visibility, being connected to the tree, etc.

positional_policy

public static positional_policy_class positional_policy

Positional input policy. This policy delivers inputs to objects which are found under the cursor.

raw_positional

public static raw_positional_agent raw_positional

Raw input event positional dispatch agent. This agent works under the positional policy and delivers raw events to objects under the cursor. This is here primarily as a hook for implementing unusual actions (although a lot of things it might be used for are probably better handled by adding new policies and/or agents, so you might want to consider that before building something with this).

move_press_drag

public static move_press_drag_agent move_press_drag

Agent that combines press and move_drag. This is a hybrid policy that accepts press then makes the object it would have been delivered to the move_drag focus.

grow_press_drag

public static grow_press_drag_agent grow_press_drag

Agent that combines press and grow_drag. This is a hybrid policy that accepts press then makes the object it would have been delivered to the grow_drag focus.

inout_press_drag

public static inout_press_drag_agent inout_press_drag

Agent for inout_press_dragging. This is a hybrid policy that accepts press then makes the object it would have been delivered to the inout_drag focus.

simple_press_drag

public static simple_press_drag_agent simple_press_drag

Agent that combines press and simple_drag . This is a hybrid policy that accepts press then makes the object it would have been delivered to the simple_drag focus.

press_click_agent

public static click_agent press_click_agent

Agent for pressable, clickable, and double_clickable.

selection_agent

public static selection_agent_class selection_agent

Agent for maintaining a currently selected set with mouse presses

point_agent

public static point_agent_class point_agent

Agent that handles the pointable protocol for telling when objects are entered or exited.

after_dispatch

protected static java.util.Vector after_dispatch

This is a list of dispatch_agents who would like to be informed whenever an event was successfully dispatched. This is important for agents which need to update their state machines on the next event regardless of who dispatched it

_event_seq_num

protected static int _event_seq_num

Counter for event sequence numbers. This is incremented for each new event. These sequence numbers are used by some parts of the system to determine when cached values associated with one event dispatch are invalid.

_an_observer

protected static java.awt.image.ImageObserver _an_observer

An ImageObserver object that does nothing. This is returned by an_observer() and used internally by the system to provide an observer object where we don't really need or want to observe.

_broken

protected static java.awt.Image _broken

An image that we provide when a requested image can't be loaded or otherwise has a problem. This will be statically initialized in memory so it will always be there.

_broken_image_icon

protected static loaded_image _broken_image_icon

A loaded_image that we provide when a requested image can't be loaded or otherwise has a problem. This will be statically initialized in memory so it will always be there.

_enable_debug_print

protected static boolean _enable_debug_print

Flag to enable (or disable) printing of debugging messages via debug_print() and/or debug_println(). Printing is enabled by default.

_marked_time

protected static long _marked_time

Timestamp for last call to mark_time()

EXCEPTION_STACK_CRASH

public static final int EXCEPTION_STACK_CRASH

Option flag to handle an unexpected exception by printing a stack trace on System.error and then exiting. This is the default.

EXCEPTION_PRINT_STACK

public static final int EXCEPTION_PRINT_STACK

Option flag to handle an unexpected exception by printing a stack trace on System.error and then continuing.

EXCEPTION_MESSAGE_CRASH

public static final int EXCEPTION_MESSAGE_CRASH

Option flag to handle an unexpected exception by printing the exception message to System.err and then exiting.

EXCEPTION_PRINT_MESSAGE

public static final int EXCEPTION_PRINT_MESSAGE

Option flag to handle an unexpected exception by printing the exception message to System.err and then continuing.

EXCEPTION_CUSTOM

public static final int EXCEPTION_CUSTOM

Option flag to handle an unexpected exception by sending the "handle_exception()" message to the object previously registered via "handle_exceptions_with()". This this object was never registered, or is null, then the default of printing a stack trace and exiting is used as a fallback.

EXCEPTION_IGNORE

public static final int EXCEPTION_IGNORE

Option flag to ignore unexpected exceptions -- this is generally a very bad idea, think twice before using this.

_handling_mechanism

protected static int _handling_mechanism

The current exception handling response. This must be one of the EXCEPTION_* option values.

_handle_object

protected static exception_handler _handle_object

The current custom exception handling object (if any). When exception handling is being done via EXCEPTION_CUSTOM, this object is passed exceptions to handle.

_cycle_handling_mechanism

protected static int _cycle_handling_mechanism

The current constraint cycle handling response. This should have one of the EXCEPTION_* values that designate a response to an unexpected exception. Default is to ignore the cycle.

_cycle_handle_object

protected static cycle_handler _cycle_handle_object

The current custom constraint handling handling object (if any). When cycle handling is being done via EXCEPTION_CUSTOM, this object is passed cycles to handle.

_default_color_pair

protected static color_pair _default_color_pair

This holds the system's default color pair

WA_DYNAMIC

public static int WA_DYNAMIC

Special platform id to support dynamically added workarounds. This allows people to temporarily put in a platform specific fix even if they can't modify identify_platform_workarounds(). In general, these id's should be avoided in favor of an "official" id. Note: there are only 32 workaround id's available under this "platform" and its up to you to avoid conflicts.

WA_USER1

public static int WA_USER1

WA_USER2

public static int WA_USER2

WA_USER3

public static int WA_USER3

WA_USER4

public static int WA_USER4

WA_USER5

public static int WA_USER5

WA_USER6

public static int WA_USER6

WA_USER7

public static int WA_USER7

WA_USER8

public static int WA_USER8

WA_USER9

public static int WA_USER9

WA_USER10

public static int WA_USER10

WA_USER11

public static int WA_USER11

WA_USER12

public static int WA_USER12

WA_USER13

public static int WA_USER13

WA_USER14

public static int WA_USER14

WA_USER15

public static int WA_USER15

WA_USER16

public static int WA_USER16

WA_USER17

public static int WA_USER17

WA_USER18

public static int WA_USER18

WA_USER19

public static int WA_USER19

WA_USER20

public static int WA_USER20

WA_USER21

public static int WA_USER21

WA_USER22

public static int WA_USER22

WA_USER23

public static int WA_USER23

WA_USER24

public static int WA_USER24

WA_USER25

public static int WA_USER25

WA_USER26

public static int WA_USER26

WA_USER27

public static int WA_USER27

WA_USER28

public static int WA_USER28

WA_USER29

public static int WA_USER29

WA_USER30

public static int WA_USER30

WA_USER31

public static int WA_USER31

WA_USER32

public static int WA_USER32

WA_NS3_ALL

public static int WA_NS3_ALL

Platform id for workarounds related to Netscape 3.x on all machines.

WA_NS3_SUN

public static int WA_NS3_SUN

Platform id for workarounds related to Netscape 3.x on Suns

WA_NS3_PC

public static int WA_NS3_PC

Platform id for workarounds related to Netscape 3.x on Wintel machines.

WA_NS3_MAC

public static int WA_NS3_MAC

Platform id for workarounds related to Netscape 3.x on the Mac

WA_TRACKER_HANGS

public static int WA_TRACKER_HANGS

WA_REDUNDANT_MOVES

public static int WA_REDUNDANT_MOVES

WA_JDK1_ALL

public static int WA_JDK1_ALL

Platform id for workarounds related to JDK 1.0.x on all machines.

WA_JDK1_SUN

public static int WA_JDK1_SUN

Platform id for workarounds related to JDK 1.0.x on Sun machines.

WA_JDK1_PC

public static int WA_JDK1_PC

Platform id for workarounds related to JDK 1.0.x on Wintel machines.

WA_JDK1_MAC

public static int WA_JDK1_MAC

Platform id for workarounds related to JDK 1.0.x on the Mac.

WA_IE3

public static int WA_IE3

Platform id for workarounds related to MS Internet Explorer 3.x.

WA_MAX_PLATFORM_ID

public static int WA_MAX_PLATFORM_ID

Largest platform id in use

_workaround_table

protected static int[] _workaround_table

Table of workaround sets. Workarounds are named by a pair of integers. The first integer is a platform id, the second is a workaround id associated with that platform. Each index in the table represents a particular platform (this is the platform that a particular bug or workaround was first identified on, it does not necessarily mean it is limited to that platform). The integer at each index represents a set of at most 32 different workarounds associated with that platform. This table is initialized at run-time by identify_platform_workarounds() (which is invoked early by a static initializer) based on some detective work to determine which platform we are actually running on.

Method Detail

default_toolkit

public static java.awt.Toolkit default_toolkit()

Get a reference the default native toolkit object. This object is useful for getting low level access to toolkit capabilities. However, the manager provides interfaces for most object types of general interest, so this object will probably be rarely used outside the manager itself.

Returns:

Toolkit the default native toolkit object.

install_standard_policies

protected static void install_standard_policies()

install_policy_after

public static void install_policy_after(input_policy add,
                                        input_policy after)

Install a new policy after an existing one (or at the end of the policy list).

Parameters:

input_policy - add the policy to add.

input_policy - after the policy to put it after. If this is null, we install at the end of the list.

install_policy_before

public static void install_policy_before(input_policy add,
                                         input_policy before)

Install a new policy before an existing one (or at the beginning of the policy list).

Parameters:

input_policy - add the policy to add.

input_policy - after the policy to put it before. If this is null, we install at the beginning of the list.

add_top_level

public static void add_top_level(top_level int_obj)

Add a top_level object to the set of active top_level objects.

Parameters:

top_level - int_obj the top_level interactor to add.

remove_top_level

public static void remove_top_level(top_level int_obj)

Remove a top_level object from the set of active top_level objects.

Parameters:

top_level - int_obj the top_level interactor to remove.

register_awt_component

public static void register_awt_component(java.awt.Component awt_comp)

Indicate that an AWT component that will be hosting a sub_arctic top_level object has been created.

Parameters:

Component - awt_comp the host component.

unregister_awt_component

public static void unregister_awt_component(java.awt.Component awt_comp)

Indicate that an AWT component that has been hosting a sub_arctic top_level object is not longer doing so.

Parameters:

Component - awt_comp the component that is no longer a host.

something_is_damaged

public static boolean something_is_damaged()

Indicate whether there is something in the system that is damaged and needs to be redrawn.

report_damage

public static void report_damage(top_level from_obj)

Report to the system that a top_level object has recorded some damage that requires it to be redrawn. This report gets passed on to AWT so that it schedules an update/repaint.

Parameters:

top_level - from_obj the object reporting the damage.

add_to_after_dispatch_list

public static void add_to_after_dispatch_list(dispatch_agent agent)

Add an agent to the list of agents interested in the after dispatch hook.

Parameters:

dispatch_agent - agent the agent to add to the list of interested agents.

remove_from_after_dispatch_list

public static void remove_from_after_dispatch_list(dispatch_agent agent)

Remove an agent from the list of dispatch_agents which are interested in the after dispatch hook. Attempting to remove an agent which is not in the list has no effect.

Parameters:

dispatch_agent - agent the agent to remove.

event_seq_num

public static int event_seq_num()

Return the sequence number for the current event. This is used by some parts of the system to determine when cached values associated with one event dispatch are invalid.

Returns:

int the sequence number for the current event.

dispatch_event

public static boolean dispatch_event(java.awt.AWTEvent evt,
                                     top_level top_obj)

This method dispatches a single event (that occurred "inside of" the given top level object) to the appropriate interactor object(s) in the interface. Note: that the event is not necessarily delivered to an object in the subtree rooted by top_obj -- this depends on the input policy object which ends up dispatching it. For example, the focus policy will send a key press event to the current text focus object regardless of where the mouse is pointing.

Note: this method is synchronized so that only one event dispatch or redraw can be going on at a time. This is necessary for maintaining the integrity of the overall system dispatch-redraw "loop". However, this is not sufficient to make the whole system thread-safe. Access to various interactor trees should always be done through the work_proc interface.

Parameters:

Event - evt the event to dispatch.

top_level - the top_level object it occured within.

do_redraw

public static void do_redraw(top_level top_obj,
                             drawable surface)

This method causes a redraw of the given interactor tree (this is normally called on the basis of a redraw request from AWT). A redraw request is handled by first laying out the objects in the interactor tree by calling configure() on the root (note: for the most part, this normally results in evaluating all the constraints that size and position objects in the tree). After all objects have been properly laid out, (which may cause additional areas of the drawable to become damaged) the smallest rectangle enclosing the damaged regions -- that is the regions which might have changed appearance in some way -- are redrawn by calling draw_self on the root of the tree.

Note: this method is synchronized so that only one event dispatch or redraw can be going on at a time. This is necessary for maintaining the integrity of the overall system dispatch-redraw "loop". However, this is not sufficient to make the whole system thread-safe. Access to various interactor trees should always be done through the work_proc interface.

Parameters:

top_level - top_obj the top_level object to redraw.

drawable - surface the drawing surface to redraw it on (this normally refers directly to the screen).

an_observer

public static java.awt.image.ImageObserver an_observer()

Return an ImageObserver that does nothing. This is useful in places where an ImageObserver object is needed, but we don't really expect to see any updates (and/or wouldn't know what to do with them if we got them).

Returns:

ImageObserver a non-observing observer object.

an_awt_component

public static java.awt.Component an_awt_component()

Return some active AWT component. Most code outside the toolkit itself should not need this, but it can be useful in various AWT routines that require some component to get a piece of information (some of this is now provided by a toolkit object obtained by default_toolkit() but not everything). If a specific component is needed, use interactor.get_awt_component() instead.

Returns:

Component an AWT Component object which is currently hosting a subArctic interface (or null if there currently are none).

an_applet

public static java.applet.Applet an_applet()

Return some active AWT applet. Most code outside the toolkit itself should not need this.

Returns:

Applet an applet object which is currently hosting a subArctic interface (or null if there currently are none).

get_metrics

public static java.awt.FontMetrics get_metrics(java.awt.Font for_font)

Get a FontMetrics object for the given font.

Parameters:

Font - for_font the font we want the metrics object for.

Returns:

FontMetrics the metrics object for that font.

broken_image_icon

public static loaded_image broken_image_icon()

Provide a standard "broken image" icon that can be used to substitute for images that couldn't be loaded for some reason or another. This gets built from static data on first use.

wait_for_image

public static boolean wait_for_image(java.awt.Image img)

Block until the given image is loaded (or there is an error in loading). Returns false if there was an error in loading.

Parameters:

Image - img the image to wait for

Returns:

boolean true if everything went ok

load_image

public static loaded_image load_image(java.net.URL from_url)

Load an image from the given URL. If or there is an error in loading, the broken image icon is returned instead.

Parameters:

URL - from_url the location to load the image from.

Returns:

loaded_image the resulting image (or the broken image if there was a problem).

load_doc_image

public static loaded_image load_doc_image(java.applet.Applet host_ap,
                                          java.lang.String image_file_name)
                                   throws java.net.MalformedURLException

Load an image from a location named relative to the document that contains the given applet. If or there is an error in loading, the broken image icon is returned instead.

Parameters:

Applet - host_ap the applet that is within the page we are fetching relative to.

String - image_file_name the name of the image file.

loaded_image - the resulting image (or the broken image if there was a problem).

load_code_image

public static loaded_image load_code_image(java.applet.Applet host_ap,
                                           java.lang.String image_file_name)
                                    throws java.net.MalformedURLException

Load an image from a location named relative to the location of the code (the .class file) for the given applet. If or there is an error in loading, the broken image icon is returned instead.

Parameters:

Applet - host_ap the applet whose code we are fetching relative to.

String - image_file_name the name of the image file.

loaded_image - the resulting image (or the broken image if there was a problem).

enable_debug_print

protected static boolean enable_debug_print()

Indicate if printing of debugging messages via debug_print() and/or debug_println() is enabled (printing is enabled by default).

Returns:

boolean enable status for debugging print routines

set_enable_debug_print

protected static void set_enable_debug_print(boolean status)

Enable (or disable) debugging messages via debug_print() and/or debug_println().

Parameters:

boolean - status flag indicating new enable status

debug_print

public static void debug_print(java.lang.String str_to_print)

Debugging print routine. This routine (conditionally) prints a string (without a newline appended) to System.err. Printing is enabled by default, but all debug printing can be stopped by calling enable_debug_print(false).

Parameters:

String - str_to_print the string to be printed

debug_println

public static void debug_println(java.lang.String str_to_print)

Debugging print routine. This routine (conditionally) prints a string (with a newline appended) to System.err. Printing is enabled by default, but all debug printing can be stopped by calling enable_debug_print(false).

Parameters:

String - str_to_print the string to be printed

mark_time

public static void mark_time()

Mark a time for debugging or performance analysis purposes. You can get the time since the last marked time by calling since_marked_time().

marked_time

public static long marked_time()

Timestamp for last call to mark_time()

Returns:

long timestamp (as returned by System.currentTimeMillis) corresponding to last call to mark_time().

since_marked_time

public static long since_marked_time()

Time since the last call to mark_time()

Returns:

long timestamp (as returned by System.currentTimeMillis()) corresponding to the time since the last call to mark_time().

sec_str

public static java.lang.String sec_str(long timestamp)

Utility routine to convert a time stamp to a string indicating seconds and milliseconds.

Parameters:

long - timestamp time (as returned by System.currentTimeMillis() to be formatted.

Returns:

string the cooresponding string formatted as seconds and milliseconds.

timed_debug_println

public static void timed_debug_println(java.lang.String str)

Debugging print routine to print a string (with newline) with the time corresponding to since_marked_time() appended. This routine uses debug_println() and is enabled and disabled in the same way.

Parameters:

String - str the string to be printed

print_stack_trace

public static void print_stack_trace(java.io.PrintStream strm)

Debugging routine to print a trace of the current call stack on on the given PrintStream, then return.

Parameters:

PrintStream - strm where we print the call stack trace.

print_stack_trace

public static void print_stack_trace()

Debugging routine to print a trace of the current call stack on on System.err, then return.

handling_mechanism

public static int handling_mechanism()

The current exception handling response. This will be one of the EXCEPTION_* option values.

handle_object

public static exception_handler handle_object()

The current custom exception handling object (if any). When exception handling is being done via EXCEPTION_CUSTOM, this object is passed exceptions to handle.

handle_exceptions_with

public static void handle_exceptions_with(int handling_type,
                                          exception_handler handler)

Establish how unexpected exceptions are handled. The handling_type parameter indicates one of several possible responses (see the EXCEPTION_* constants). The handler parameter indicates an object that will handle the exception if EXCEPTION_CUSTOM is used (it can passed is null otherwise).

Parameters:

int - handling_type code indicating how to handle an unexpected exception.

exception_handler - handler the handler object that gets the exception if handling_type is EXCEPTION_CUSTOM.

handle_exceptions_with

public static void handle_exceptions_with(int handling_type)

Establish how unexpected exceptions are handled. The handling_type parameter indicates one of several possible standard responses (see the EXCEPTION_* constants).

Parameters:

int - handling_type code indicating how to handle an unexpected exception.

handle_unexpected_exception

public static void handle_unexpected_exception(java.lang.Exception except)

Handle an unexpected exception that arrived at some part of the toolkit. The specific action undertaken is controlled by the last call to handle_exceptions_with().

Parameters:

Exception - except the unexpected exception.

See Also:

#handle_exceptions_with()

cycle_handling_mechanism

public static int cycle_handling_mechanism()

The current constraint cycle handling response. This should have one of the EXCEPTION_* values that designate a response to an unexpected exception. Default is to ignore the cycle.

cycle_handle_object

public static cycle_handler cycle_handle_object()

The current custom exception handling object (if any). When cycle handling is being done via EXCEPTION_CUSTOM, this object is passed cycles to handle.

handle_cycles_with

public static void handle_cycles_with(int handling_type,
                                      cycle_handler handler)

Establish how constraint cycles are handled. The handling_type parameter indicates one of several possible responses (see the EXCEPTION_* constants). The handler parameter indicates an object that will handle the cycle if EXCEPTION_CUSTOM is used (it can be passed as null otherwise).

Parameters:

int - handling_type the code indicating how to handle the cycle.

cycle_handler - handler the optional handler object used when handling_type is EXCEPTION_CUSTOM.

handle_cycles_with

public static void handle_cycles_with(int handling_type)

Establish how constraint cycles are handled. The handling_type parameter indicates one of several possible standard responses (see the EXCEPTION_* constants).

Parameters:

int - handling_type the code indicating how to handle the cycle.

handle_cycle

public static boolean handle_cycle(interactor in_obj,
                                   int part_code)

Handle a cycle. If normal processing at the point of the cycle is to proceed, true is returned. Otherwise, the caller of this routine should leave the current value in the attribute marked up-to-date (this only happens with custom handlers).

Parameters:

interactor - in_obj the interactor in which the cycle was first detected.

int - part_code the part within that object where the cycle was first detected.

establish_extern_constraint

public static void establish_extern_constraint(value_consumer cons_obj,
                                               int cons_part,
                                               value_provider prov_obj,
                                               int prov_part)

Establish an associative link between the given part of a value_consumer (usually an interactor) and part of a value_provider (usually an external_constraint) that gives it a value. (This is part of the "external" or "heavyweight" constraint system.)

Parameters:

value_consumer - cons_obj the object being constrained.

int - cons_part the part within that object being constrained.

value_provider - prov_obj the object (often a constraint) providing the value.

int - prov_part the part of that object that provides the value.

drop_extern_constraint

public static void drop_extern_constraint(value_consumer cons_obj,
                                          int cons_part)

Remove any association between the given part of a value_consumer and a value_producer. (This is part of the "external" or "heavyweight" constraint system.)

Parameters:

value_consumer - cons_obj the object that was being constrained.

int - cons_part the part within that object that was being constrained.

value_provider - prov_obj the object (often a constraint) that was providing the value.

int - prov_part the part of that object that was providing the value.

find_extern_constraint

public static provider_part_ref find_extern_constraint(value_consumer cons_obj,
                                                       int cons_part)

Get the value_provider and part associated with the given value_consumer part. Returns null if no such association has been stored. (This is part of the "external" or "heavyweight" constraint system.)

Parameters:

value_consumer - cons_obj the consumer object we determining the provider (typically constraint) for.

int - cons_part the part of that object we are asking about.

Returns:

provider_part_ref a reference to the object and part providing the inquired about value, or null if there is none.

add_to_ood_notify

public static void add_to_ood_notify(value_provider for_prov,
                                     int for_part,
                                     value_consumer notify_obj,
                                     int notify_part)

Add an element to the notify list being maintained for the given value_provider part. This list represents the set of things that need to be informed when the provider part changes value (or might have changed value).

Parameters:

value_provider - for_prov the object (providing a value) which needs to inform others of changes.

int - for_part the part of that object we are concerned with.

value_consumer - notify_obj the object we are to notify.

int - notify_part the part of that object we are to notify.

remove_ood_notify

public static boolean remove_ood_notify(value_provider for_prov,
                                        int for_part,
                                        value_consumer notify_obj,
                                        int notify_part)

Remove an element from the notify list being maintained for the given value_provider part. Return true if the list is then empty.

Parameters:

value_provider - for_prov the object (providing a value) which had been notifying.

int - for_part the part of that object we are concerned with.

value_consumer - notify_obj the object we were to notify.

int - notify_part the part of that object we were to notify.

get_ood_notify

public static java.util.Vector get_ood_notify(value_provider for_prov,
                                              int for_part)

Get the notify list being maintained for the given value_provider part. Returns null if no list items has been stored for the provider.

Parameters:

value_provider - for_prov the object we are asking about.

int - for_part the part of that object whose notify list we want.

Returns:

Vector a vector of consumer_part_ref objects that the given object/part is to notify should it change (or null if no notify list has been stored for that object).

build_broken_icon

protected static java.awt.Image build_broken_icon()

Build the "broken image" icon from static data.

Returns:

Image the broken image icon.

default_color_pair

public static color_pair default_color_pair()

This function returns the default color pair for the system.

Note: This is now obsolete -- use the style system instead.

Returns:

color_pair the system's default color pair

unique_int

public static int unique_int()

Return a positive integer value that is unique among results from this routine (we ignore the fact that this will eventually wrap-around, so if you need one every micro-second, do it yourself with a long).

perform_work

public static void perform_work(work_proc wp,
                                java.lang.Object arg)

You can call this method from another thread and it will perform the work represented by the work_proc with the system in a safe synchronization state.

Parameters:

work_proc - wp an object representing what code to run with the system in a safe state (its really a closure, in some sense).

Object - arg the argument to pass to the work_proc when the system reaches a safe state.

dump_platform_properties

public static void dump_platform_properties()

Helper routine to dump useful system properties to System.out. You can use this to determine at least part of the "signature" of a new platform that you need to incorporate into identify_platform_workarounds().

identify_platform_workarounds

protected static void identify_platform_workarounds()

Do the detective work to determine which platform we are on and hence which set of platform specific work arounds should be enabled. This will be called once by a static initializer here in the manager. It sets up the _workaround_table array used by need_workaround() to determine which platform specific workarounds are needed and which are not.

Editorial Comment: The need for this routine is a very clear indication that Java, and in particular AWT, has as of yet utterly and completely failed to deliver on the promise of "write once run everywhere".

need_workaround

public static boolean need_workaround(int platform_id,
                                      int workaround_id)

Determine if a given platform specific workaround (identified by a platform id and workaround id pair) is needed on the platform we are currently running on. Note: workarounds are not necessarily limited to the platform whose id they are associated with -- this is just the first platform for which the workaround was identified and helps segregate the workaround id name space and make it more extensible.

Editorial Comment: The need for this routine is a very clear indication that Java, and in particular AWT, has as of yet utterly and completely failed to deliver on the promise of "write once run everywhere".

Parameters:

int - platform_id First part of identification of a particular workaround (this identifies the platform that the workaround was first associated with).

int - workaround_id Second part of identification of a particular workaround (this uniquely identifies it within the group associated with a platform).

Returns:

boolean indicating whether the given workaround is needed on the platform we are currently running on.

activate_workaround

public static void activate_workaround(int platform_id,
                                       int workaround_id)

Activate a specific platform specific workaround. This is here to allow activation of known workarounds on the basis of new circumstances (or circumstances that can only be determined dynamically). This can also be used with the WA_DYNAMIC platform id for indicating temporary platform specific fixes without updating identify_platform_workarounds(). (Such usage should be only temporary, however, because there are only 32 such workaround id's available and no conflict resolution scheme is provided.)

Parameters:

int - platform_id First part of identification of the particular workaround to the activated (this identifies the platform that the workaround was first associated with).

int - workaround_id Second part of identification of the particular workaround to be activated (this uniquely identifies it within the group associated with a platform).

set_event_dispatch_handler

public static void set_event_dispatch_handler(dispatch_handler edh)

This function is used to set the dispatch result handler. Whenever an event is successfully dispatched by the system, an event_dispatch object is created and the dispatch result handler (if one has been installed) will be invoked. If you pass null as the parameter to this function, the system will not use a handler. Be aware that some agents call dispatch_handler themselves (although via the send_dispatch_result_to_handler method below) because they are speaking an input protocol in response to a programmatic call.

Before using this hook, be sure you understand how the dispatch_handler interface is intended to be used. It is not intended to be used to filter or control the routing of events; if you want this type of behavior, put an agent in the monitor_focus_policy instead.

Parameters:

dispatch_handler - edh the handler to route dispatches to

event_dispatch_handler

public static dispatch_handler event_dispatch_handler()

Retreive the current event dispatch handler.

Returns:

event_dispatch_handler the currently installed handler or null if there is no current handler

send_dispatch_result_to_handler

public static void send_dispatch_result_to_handler(dispatch_result dr)

Send a dispatch_result to the current dispatch handler, if one exists. If none exists, this function does nothing. Some agents may call this themselves if they are doing a dispatch in result to a programmatic call, such as "set_focus_so".

Parameters:

dispatch_result - the result of a successful dispatch