sub_arctic.lib
Class interactor_frame

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Window
                    |
                    +--java.awt.Frame
                          |
                          +--sub_arctic.lib.interactor_frame
Direct Known Subclasses:
FileDialogFrame
public class interactor_frame
extends java.awt.Frame
implements std_constraint_consts

This class allows you to put up an external frame with a sub arctic interface in it. Note that this is an AWT container, so if you want its size, location, etc. you have to use the AWT calls.

Since this is an AWT frame you'll need to call dispose to release the resource for this object ('hide' just gets it off screen) unless the user does the "go away" box, in which case we dispose of it.

This object supports a callback. It will get called with a callback_num of 0 and a null callback_object. The interactor making the call will be the top_level of this frame. This callback is called when the user closes the window (only). Note that the callback is called with a null event. We don't have a sub arctic event at the time of the callback!

Subtle point about inside-out interfaces: If you want an "inside-out" type of sizing behavior you should be aware of this: If you use constraints on your top_level to compute the inside-out layout (and be careful to insure you don't get cycles) they will be REMOVED when you call show on this object. The last value will preserved, so the initial size will be whatever the result of the constraints were; we remove the constraints because the size of your top_level is tied to the size of the AWT component it is living in and these components get (stupidly) resized a couple of times (including going through zero!) before the interface ends up on the screen. Thus, you would get an exception because you would end up trying to assign to a constrained value. Trust me on this one thing: If you use constraints to compute your inside-out interface and then use the "setResizable" method to not allow the user to resize your interface, everything will work out.

If you are using this object to make a window for an already constructed interface (i.e you supply a non-null top_level) none of the normal build_ui type of methods will get called. We assume you are already "done" with UI construction. If you want to build the UI after this frame is constructed, pass a null value to any of the constructors of this class and we will go through the same sequence as interactor_applet for constructing the interface (pre_build_ui()) build_ui() and then post_build_ui()) at show time. That is to say that your build_ui() type methods will not get called until the object is shown. We do this to allow the object's constructor to complete before we run the code to construct the UI. If you want to force an interface build you can call initialize() yourself.

If you use the approach of building the UI in the build_ui methods, & don't explicitly set a size, the size of the frame will be computed based on the size of your top_level after the call to post_build_ui().

See Also:
Serialized Form

Field Summary
protected  callback_object _obj
          Callback object.
protected  top_level _top
          Storage and accessor for the toplevel.
protected  boolean _ui_constructed
          hold onto whether or not the UI is built
 
Fields inherited from class java.awt.Frame
CROSSHAIR_CURSOR, DEFAULT_CURSOR, E_RESIZE_CURSOR, HAND_CURSOR, ICONIFIED, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NORMAL, NW_RESIZE_CURSOR, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, W_RESIZE_CURSOR, WAIT_CURSOR
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Constructor Summary
interactor_frame(java.lang.String n, interactor_applet a, int w, int h)
          This is a convenience function for replicating applets in frames.
interactor_frame(java.lang.String title, int fw, int fh, top_level tl)
          Construct an interactor_frame.
interactor_frame(java.lang.String title, top_level tl)
          Construct an interactor_frame from a top_level.
 
Method Summary
 void build_ui(base_parent_interactor top)
          This function gets called so you can construct your user interface.
 callback_object callback_obj()
          Retrieve the callback object associated with this interactor_frame.
 void initialize()
          This function gets called to force the UI to get built if there is no top_level and the UI has not been previously built.
 void make_top_level(int w, int h)
          This function is called to create an install a top_level interactor in this applet.
 java.awt.Dimension minimumSize()
          This function is part of the AWT world.
 void post_build_ui(base_parent_interactor t)
          This function is called to allow you to process the now constructed interactor tree after its built.
 void pre_build_ui()
          This function is called to allow you to initialize data structures that are needed for building the UI.
 java.awt.Dimension preferredSize()
          This function is part of the AWT world.
 void processEvent(java.awt.AWTEvent e)
          This function gets called to inform us about window events.
 void set_callback_obj(callback_object o)
          Change the object we will make the callbacks on.
 void show()
          We override the show() method to make sure the sub_arctic interface is constructed.
 top_level top_interactor()
          Access the top level interactor for this frame.
 boolean ui_constructed()
          Determine if the user interface has been constructed.
 
Methods inherited from class java.awt.Frame
addNotify, finalize, getCursorType, getFrames, getIconImage, getMenuBar, getState, getTitle, isResizable, paramString, remove, removeNotify, setCursor, setIconImage, setMenuBar, setResizable, setState, setTitle
 
Methods inherited from class java.awt.Window
addWindowListener, applyResourceBundle, applyResourceBundle, dispose, getFocusOwner, getInputContext, getLocale, getOwnedWindows, getOwner, getToolkit, getWarningString, isShowing, pack, postEvent, processWindowEvent, removeWindowListener, toBack, toFront
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, paint, paintComponents, print, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setFont, setLayout, update, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputMethodRequests, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_obj

protected callback_object _obj
Callback object.

_top

protected top_level _top
Storage and accessor for the toplevel.

_ui_constructed

protected boolean _ui_constructed
hold onto whether or not the UI is built
Constructor Detail

interactor_frame

public interactor_frame(java.lang.String title,
                        int fw,
                        int fh,
                        top_level tl)
Construct an interactor_frame. This object will be initially set up to have a certain size. If you supply null as the top_level we will go through the sequence pre_build_ui(), build_ui() and post_build_ui() to allow you to construct the interface. Note that the size of the resulting frame will be the values supplied to this function independent of the size of the constructed top_level.
Parameters:
String - title the title for this window when it gets to the screen
int - fw the width of the new frame
int - fh the height of the new frame
top_level - tl the top_level to put in this frame

interactor_frame

public interactor_frame(java.lang.String title,
                        top_level tl)
Construct an interactor_frame from a top_level. We deduce the size of the interactor_frame from the top_level, so be sure have your top_level sized correctly (probably using constraints) or this object will end up with the wrong size. If you pass null here for the top_level, we go through the usual sequence of calls to pre_build_ui(), buid_ui() and then post_build_ui(). That sequence will be called at the time you call show() or you can do it explicitly with initialize().

After that sequence we compute the size of your top_level and use that to size the frame. Note: Initially your top_level is sized to be 10x10 pixels, so if you don't want your interface to be that size, you should size it in one of these calls or install constraints on it.

This ends up calling the static routine on interactor_canvas to derive the size and remove the constraints.

Parameters:
String - title the title for this window on the screen
top_level - tl the top_level to put in this frame

interactor_frame

public interactor_frame(java.lang.String n,
                        interactor_applet a,
                        int w,
                        int h)
This is a convenience function for replicating applets in frames. If you use this method, this method will call init() on your applet (so the applet will get the associated pre_build_ui(), build_ui() and post_build_ui() functions) and the interactor frame will not get he build_ui() calls. You have to supply a size for this applet because applets expect to be given a size via their browser. Your applet might get confused if you have already called init() on it before you call this constructor.
Parameters:
String - n the name of the frame
interactor_applet - a the applet to insert in this frame
int - w the width of this frame
int - h the height of this frame
Method Detail

callback_obj

public callback_object callback_obj()
Retrieve the callback object associated with this interactor_frame.
Returns:
callback_object the object this frame makes callbacks on

set_callback_obj

public void set_callback_obj(callback_object o)
Change the object we will make the callbacks on.
Parameters:
callback_object - o the new callback target

top_interactor

public top_level top_interactor()
Access the top level interactor for this frame.
Returns:
top_level this interactor_frame's top level

processEvent

public void processEvent(java.awt.AWTEvent e)
This function gets called to inform us about window events. We forward these along to the manager.
Overrides:
processEvent in class java.awt.Window

preferredSize

public java.awt.Dimension preferredSize()
This function is part of the AWT world. It is supposed to be called by layout manager's to ask us how big we would like to be. We just tell it our minimum size.

Its not clear when, where, why, or if this function will actually be called by a layout manager.

Returns:
Dimension the dimensions we prefer for this frame.
Overrides:
preferredSize in class java.awt.Container

minimumSize

public java.awt.Dimension minimumSize()
This function is part of the AWT world. It is supposed to be called by layout manager's to ask how what the minimal amount of screen space we can live with is.We return the size that the user initially gave us when this object was created.

Its not clear when, where, why, or if this function will actually be called by a layout manager.

Returns:
Dimension the minimum dimension we can live with
Overrides:
minimumSize in class java.awt.Container

pre_build_ui

public void pre_build_ui()
This function is called to allow you to initialize data structures that are needed for building the UI. By default, it does nothing.

post_build_ui

public void post_build_ui(base_parent_interactor t)
This function is called to allow you to process the now constructed interactor tree after its built.
Parameters:
base_parent_interactor - t root of the newly constructed tree

make_top_level

public void make_top_level(int w,
                           int h)
This function is called to create an install a top_level interactor in this applet. By default it creates a toplevel of the same size as the interactor and then installs it.
Parameters:
int - w the width of the new top_level to construct
int - h the height of the new top_level

build_ui

public void build_ui(base_parent_interactor top)
This function gets called so you can construct your user interface. The top_level provided is already installed as the root of your interactor tree for this applet. By default, this function does nothing.
Parameters:
base_parent_interactor - top the new root interactor for this applet

ui_constructed

public boolean ui_constructed()
Determine if the user interface has been constructed.
Returns:
boolean true if the UI has been built

initialize

public void initialize()
This function gets called to force the UI to get built if there is no top_level and the UI has not been previously built. Calls other than the first one to initialize() don't have any effect. This function gets called automatically by the show() routine.

show

public void show()
We override the show() method to make sure the sub_arctic interface is constructed.
Overrides:
show in class java.awt.Window