sub_arctic.lib
Class listbox_display

java.lang.Object
  |
  +--sub_arctic.lib.min_interactor
        |
        +--sub_arctic.lib.base_interactor
              |
              +--sub_arctic.lib.base_parent_interactor
                    |
                    +--sub_arctic.lib.listbox_display

Direct Known Subclasses:

listbox

public class listbox_display

extends base_parent_interactor

implements callback_object

This is the class that handles the output side of the behavior of a listbox. It has no input behavior of its own.

Field Summary

protected listbox_child_display	_child_display The underlying listbox_display_children.
protected listbox_helper	_display_parent The parent interactor which holds the listbox display and the horiz scrollbar.
protected h_scrollbar	_external_h_scrollbar This is an "external" horizontal scrollbar.
protected v_scrollbar	_external_v_scrollbar This is an "external" vertical scrollbar.
protected h_scrollbar	_horiz This is the horizontal scrollbar for this listbox (which is created even if not used.
protected int	_horiz_status This holds the status of the horizontal scrollbar.
protected v_scrollbar	_vert This is the vertical scrollbar for this listbox (which is created even if not used).
protected int	_vert_status This holds the status of the vertical scrollbar.
static int	SCROLLBAR_ALWAYS This is the constant which expresses that you always want a scrollbar, even if the display doesn't fill the object.
static int	SCROLLBAR_AS_NECESSARY This is the constant which expresses that you want scrollbars only when they are necessary.
static int	SCROLLBAR_NEVER This is the constant which expresses that you never want a scrollbar, no matter what the size of the list.

Fields inherited from class sub_arctic.lib.base_interactor

_child_index, _child_list, _clip_bounds, _constraint_flags, _enabled_constraint, _flags, _h, _h_constraint, _parent, _part_a_constraint, _part_b_constraint, _user_data, _visible_constraint, _w, _w_constraint, _x, _x_constraint, _y, _y_constraint, default_child_hint

Constructor Summary

listbox_display()
Create a new listbox display.

listbox_display(int w, int h)
Create a new listbox display with a given size.

Method Summary

int	above_space() Retrieve the above spacing around a listbox.
void	add_to_selected_set(int start, int end) Add objects to the selected set.
int	below_space() Retrieve the below spacing around a listbox.
void	callback(interactor from_obj, event evt, int callback_num, java.lang.Object callback_info) This is the callback object code.
void	child_size_changed() This method is called by our child to tell us the size has changed.
void	clear_selected() Clear the set of selected items.
void	clear() Clear the set of objects that are displayed.
void	configure() We override configure so we can become informed of our size changing and do the resizing of the displayed objects if necessary.
java.util.Vector	contents_raw() Retreive the contents of the listbox as list_elements.
java.util.Vector	contents() Retreive the contents of the listbox transformed by the listbox elements via convert_to_object.
void	ensure_thumb_size() This function is called to ensure that the size displayed by the scrollbar thumb(s) is correct.
void	ensure_visible(int target) This function makes sure that a given index position of the selected_set is visible on the screen.
boolean	have_v_scrollbar() This is a utility to find out if we have (our own, not an external) scrollbar.
h_scrollbar	horizontal_scrollbar() This function returns the current horizontal scrollbar for the purposes of callback handling and the setting of the scrollbar thumb.
int	horizontal_status() Retrieve the status of the horizontal scrollbar.
int	index_for_screen_point(int y) This is a convenience function for users to call when they want to know what index is at a given screen cordinate.
int	left_space() Retrieve the left hand spacing around a listbox.
protected void	move_down() This function gets called (via the special scrollbar) when the user wishes to move to the next item.
protected void	move_up() This function gets called (via the special scrollbar) when the user wishes to move to the previous item.
protected void	reconfigure_children() This function is the one that does the work of deciding if we need the scrollbars and if so how big the thumbs of the scrollbars should be.
void	remove_from_selected_set(int start, int end) Remove a items from the selected set based on their item number.
int	right_space() Retrieve the right hand spacing around a listbox.
java.util.Vector	selected_set_raw() This function retreives the currently selected set of objects as list_elements.
java.util.Vector	selected_set() This function retreives the currently selected set of objects as values.
void	set_above_space(int v) Set the above spacing around a listbox.
void	set_below_space(int v) Set the below spacing around a listbox.
void	set_contents(java.util.Vector contents) Set the objects that are displayed.
void	set_external_h_scrollbar(h_scrollbar n) This function sets the external horizontal scrollbar.
void	set_external_v_scrollbar(v_scrollbar n) This function sets the external vertical scrollbar.
void	set_horizontal_status(int status) Set the status of the horizontal scrollbar.
void	set_left_space(int v) Set the left hand spacing around a listbox.
void	set_right_space(int v) Set the right hand spacing around a listbox.
void	set_scrolled_x(int x) This function will move the scrolled object (the display of objects) to a particular logical point in x.
void	set_scrolled_y(int y) This function will move the scrolled object in such a way that the parameter given will be at the top of the displayed area. It takes into account margins and bevelling.
void	set_selected_by_index(java.util.Vector selected) This functions sets the selected set of objects by their index numbers.
void	set_selected(java.util.Vector selected) Set the selected set of objects.
void	set_vertical_status(int status) Set the status of the vertical scrollbar.
protected void	setup_children() This function gets called to set up the heirarchy of interactors that a listbox needs.
v_scrollbar	vertical_scrollbar() This function returns the current vertical scrollbar for the purposes of callback handling and the setting of the scrollbar thumb.
int	vertical_status() Retrieve the status of the vertical scrollbar.

Methods inherited from class sub_arctic.lib.base_interactor

active_constraints, add_child, add_user_datum, attach_dependent, bound, callback_obj, child_index, child, clear_child_list, clear_constraint_flag_bit, clear_flag_bit, constraint_flag_is_set, constraint_flag_string, constraint_on, custom_fun1, custom_fun2, damage_fixed, damage_from_child, damage_self, damage_self, damage_self, damage_self, damage_self, detach_dependent, do_action, do_action, do_callback, do_callback, drag_feature_point, draw_children, draw_self_local, draw_self, enabled_constraint, enabled, enter_local_coordinates, eval_enabled, eval_h, eval_part_a, eval_part_b, eval_visible, eval_w, eval_x, eval_y, eval, exit_local_coords, feature_point_enabled, feature_point, filter_pt, find_child, first_callback_num, fixed_children, flag_is_set, flag_string, focus_set_enter, focus_set_exit, get_awt_component, get_external_constraint, get_part, get_top_level, get_value, global_to_local, global_to_local, h_constraint, h, handle_cycle, inform_ood, insert_child, inside_bounds, into_local, into_local, into_parent, into_parent, intrinsic_constraints, is_constrained, last_callback_num, local_to_global, local_to_global, mark_all_ood, mark_enabled_ood, mark_h_ood, mark_ood, mark_part_a_ood, mark_part_b_ood, mark_reparented_ood, mark_visible_ood, mark_w_ood, mark_x_ood, mark_y_ood, marked_ood, move_child_downward, move_child_downward, move_child_to_bottom, move_child_to_bottom, move_child_to_top, move_child_to_top, move_child_upward, move_child_upward, move_downward, move_to_bottom, move_to_top, move_upward, new_look_configure, next_sibling, num_actions, num_children, num_feature_points, ood_inform_all, parent, part_a_constraint, part_a, part_b_constraint, part_b, pick_within_children, pick, picked_by, pos, prev_sibling, register_resource_names, remove_child, remove_child, remove_user_datum, restyle_look_resources, restyle, set_callback_obj, set_child_index, set_child, set_constraint_flag_bit, set_constraint_flag_bit, set_constraint, set_constraint, set_enabled_constraint, set_enabled_constraint, set_enabled_constraint, set_enabled, set_flag_bit, set_flag_bit, set_h_constraint, set_h_constraint, set_h_constraint, set_h, set_intrinsic_h, set_intrinsic_size, set_intrinsic_w, set_parent, set_part_a_constraint, set_part_a_constraint, set_part_a_constraint, set_part_a, set_part_b_constraint, set_part_b_constraint, set_part_b_constraint, set_part_b, set_pos, set_pos, set_raw_enabled, set_raw_h, set_raw_part_a, set_raw_part_b, set_raw_visible, set_raw_w, set_raw_x, set_raw_y, set_size, set_style_lock, set_user_info, set_visible_constraint, set_visible_constraint, set_visible_constraint, set_visible, set_w_constraint, set_w_constraint, set_w_constraint, set_w, set_x_constraint, set_x_constraint, set_x_constraint, set_x, set_y_constraint, set_y_constraint, set_y_constraint, set_y, setup_for_children, setup_for_children, setup_for_fixed_children, size, style_change_local, style_change, supports_children, tag_str, toString, traverse_and_collect_children, traverse_and_collect_parent, traverse_and_collect, trivial_reject, trivial_reject, user_data, user_info, value_ood, visible_constraint, visible, w_constraint, w, x_constraint, x_into_local, x_into_parent, x, y_constraint, y_into_local, y_into_parent, y

Methods inherited from class java.lang.Object

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

Field Detail

_child_display

protected listbox_child_display _child_display

The underlying listbox_display_children.

_display_parent

protected listbox_helper _display_parent

The parent interactor which holds the listbox display and the horiz scrollbar.

_horiz

protected h_scrollbar _horiz

This is the horizontal scrollbar for this listbox (which is created even if not used.

_vert

protected v_scrollbar _vert

This is the vertical scrollbar for this listbox (which is created even if not used).

_external_v_scrollbar

protected v_scrollbar _external_v_scrollbar

This is an "external" vertical scrollbar. This is set to a value by the user if he wishes to have an external scrollbar control the listbox.

_external_h_scrollbar

protected h_scrollbar _external_h_scrollbar

This is an "external" horizontal scrollbar. This is set to a value by the user if he wishes to have an external scrollbar control the listbox.

SCROLLBAR_AS_NECESSARY

public static final int SCROLLBAR_AS_NECESSARY

This is the constant which expresses that you want scrollbars only when they are necessary.

SCROLLBAR_ALWAYS

public static final int SCROLLBAR_ALWAYS

This is the constant which expresses that you always want a scrollbar, even if the display doesn't fill the object.

SCROLLBAR_NEVER

public static final int SCROLLBAR_NEVER

This is the constant which expresses that you never want a scrollbar, no matter what the size of the list. This presumes you are going to handle the scrolling yourself.

_vert_status

protected int _vert_status

This holds the status of the vertical scrollbar.

_horiz_status

protected int _horiz_status

This holds the status of the horizontal scrollbar.

Constructor Detail

listbox_display

public listbox_display()

Create a new listbox display. It defaults to adding scrollbars on demand. It also defaults to a location of 0,0 so you must use constraints or position this object yourself. Its size will be 150x100.

listbox_display

public listbox_display(int w,
                       int h)

Create a new listbox display with a given size. It defaults to adding scrollbars on demand; it sets its position to 0, 0 so either position it with constraints or set the coordinates directly.

Parameters:

int - w the width of the interactor

int - h the height of the interactor

Method Detail

setup_children

protected void setup_children()

This function gets called to set up the heirarchy of interactors that a listbox needs.

vertical_status

public int vertical_status()

Retrieve the status of the vertical scrollbar. This status will be one of SCROLLBAR_AS_NECESSARY, SCROLLBAR_ALWAYS, or SCROLLBAR_NEVER.

horizontal_status

public int horizontal_status()

Retrieve the status of the horizontal scrollbar. This status will be one of SCROLLBAR_AS_NECESSARY, SCROLLBAR_ALWAYS, or SCROLLBAR_NEVER.

set_vertical_status

public void set_vertical_status(int status)

Set the status of the vertical scrollbar. The value passed to this function must be one of the constants SCROLLBAR_AS_NECESSARY, SCROLLBAR_ALWAYS, or SCROLLBAR_NEVER.

set_horizontal_status

public void set_horizontal_status(int status)

Set the status of the horizontal scrollbar. The value passed to this function must be one of the constants SCROLLBAR_AS_NECESSARY, SCROLLBAR_ALWAYS, or SCROLLBAR_NEVER.

child_size_changed

public void child_size_changed()

This method is called by our child to tell us the size has changed.

configure

public void configure()

We override configure so we can become informed of our size changing and do the resizing of the displayed objects if necessary.

Overrides:

configure in class base_interactor

clear

public void clear()

Clear the set of objects that are displayed.

set_contents

public void set_contents(java.util.Vector contents)

Set the objects that are displayed. This vector must contain only list_element objects.

Parameters:

Vector - contents the objects to display

contents

public java.util.Vector contents()

Retreive the contents of the listbox transformed by the listbox elements via convert_to_object. If the listbox is empty, this will return an empty Vector.

Returns:

Vector the contents of the listbox

contents_raw

public java.util.Vector contents_raw()

Retreive the contents of the listbox as list_elements. If the listbox is empty, this will return an empty Vector.

Returns:

Vector the contents of the listbox

set_selected

public void set_selected(java.util.Vector selected)

Set the selected set of objects. This vector must contain only list_element objects or it can be null to clear all selections.

Parameters:

Vector - selected the objects which are now to be selected

add_to_selected_set

public void add_to_selected_set(int start,
                                int end)

Add objects to the selected set. This takes two integers which are object numbers of the objects you wish to be selected. If these objects are already selected, this does not select them again.

Parameters:

int - start the first object to be added

int - end the last object to be added (inclusive)

remove_from_selected_set

public void remove_from_selected_set(int start,
                                     int end)

Remove a items from the selected set based on their item number. If the item isn't in the selected set, it doesn't do anything.

Parameters:

int - start the first item to remove

clear_selected

public void clear_selected()

Clear the set of selected items.

callback

public void callback(interactor from_obj,
                     event evt,
                     int callback_num,
                     java.lang.Object callback_info)

This is the callback object code. We use this to get the information from the scrollbars.

Specified by:

callback in interface callback_object

Parameters:

interactor - from_obj the source of the callback

event - evt the event causing the callback

int - callback_num the callback number

Object - callback_info the callback supplied information

reconfigure_children

protected void reconfigure_children()

This function is the one that does the work of deciding if we need the scrollbars and if so how big the thumbs of the scrollbars should be.

set_scrolled_x

public void set_scrolled_x(int x)

This function will move the scrolled object (the display of objects) to a particular logical point in x. This function does the work of dealing with moving the scrolled to the correct point which is not the same as the input point due to margins and bevelling.

Parameters:

int - x the new x position of the scrolled object

set_scrolled_y

public void set_scrolled_y(int y)

This function will move the scrolled object in such a way that the parameter given will be at the top of the displayed area.

It takes into account margins and bevelling.

Parameters:

int - y in the index of the object to display

move_down

protected void move_down()

This function gets called (via the special scrollbar) when the user wishes to move to the next item.

move_up

protected void move_up()

This function gets called (via the special scrollbar) when the user wishes to move to the previous item.

selected_set_raw

public java.util.Vector selected_set_raw()

This function retreives the currently selected set of objects as list_elements. This is primarily useful if you wish to address these objects as interactors, rather than as data values.

Returns:

Vector a vector of list_elements which are those objects that are currently selected. This will return an empty (not null) Vector if the selected set is currently empty

selected_set

public java.util.Vector selected_set()

This function retreives the currently selected set of objects as values. list_element objects which support the "convert_to_object" method will return a more convenient representation of themselves, and those that done will be returned as list_elements. If nothing is selected, this will return an empty (not null) vector.

Returns:

Vector a vector of selected set objects

ensure_visible

public void ensure_visible(int target)

This function makes sure that a given index position of the selected_set is visible on the screen.

Parameters:

int - target the object's index to make visible

set_selected_by_index

public void set_selected_by_index(java.util.Vector selected)

This functions sets the selected set of objects by their index numbers.

Parameters:

Vector - selected a vector of Integer objects

vertical_scrollbar

public v_scrollbar vertical_scrollbar()

This function returns the current vertical scrollbar for the purposes of callback handling and the setting of the scrollbar thumb. This always returns a scrollbar, even if no scrollbar is visible. Also, this should only be used when one is considering manipulating the size of the thumb, the minimum/maximum values, and handling callbacks as it may be a user scrollbar somewhere on the screen other than connected to the listbox.

Returns:

v_scrollbar the h_scrollbar in use

horizontal_scrollbar

public h_scrollbar horizontal_scrollbar()

This function returns the current horizontal scrollbar for the purposes of callback handling and the setting of the scrollbar thumb. This always returns a scrollbar, even if no scrollbar is visible. Also, this should only be used when one is considering manipulating the size of the thumb, the minimum/maximum values, and handling callbacks as it may be a user scrollbar somewhere on the screen other than connected to the listbox.

Returns:

h_scrollbar the h_scrollbar in use

set_external_v_scrollbar

public void set_external_v_scrollbar(v_scrollbar n)

This function sets the external vertical scrollbar. If you use this function, the scrollbar supplied here will control this listbox's vertical position. You will probably want to use a listbox_v_scrollbar rather than a normal v_scrollbar for this. You should pass null to reset this object to not using an external scrollbar.

Parameters:

v_scrollbar - n the new vertical scrollbar

set_external_h_scrollbar

public void set_external_h_scrollbar(h_scrollbar n)

This function sets the external horizontal scrollbar. If you use this function, the scrollbar supplied here will control this listbox's horizontal position.

Parameters:

h_scrollbar - n the new horizontal scrollbar

right_space

public int right_space()

Retrieve the right hand spacing around a listbox.

Returns:

int the number of pixels drawn to the right of a listboxes edge

left_space

public int left_space()

Retrieve the left hand spacing around a listbox.

Returns:

int the number of pixels drawn to the left of a listboxes edge

above_space

public int above_space()

Retrieve the above spacing around a listbox.

Returns:

int the number of pixels drawn above a listboxes

below_space

public int below_space()

Retrieve the below spacing around a listbox.

Returns:

int the number of pixels drawn to below a listbox

set_right_space

public void set_right_space(int v)

Set the right hand spacing around a listbox.

Parameters:

int - v the new value for the spacing

set_left_space

public void set_left_space(int v)

Set the left hand spacing around a listbox.

Parameters:

int - v the new value for the spacing

set_above_space

public void set_above_space(int v)

Set the above spacing around a listbox.

Parameters:

int - v the new value for the spacing

set_below_space

public void set_below_space(int v)

Set the below spacing around a listbox.

Parameters:

int - v the new value for the spacing

ensure_thumb_size

public void ensure_thumb_size()

This function is called to ensure that the size displayed by the scrollbar thumb(s) is correct. This also updates the min, max, and current values of the thumb(s).

have_v_scrollbar

public boolean have_v_scrollbar()

This is a utility to find out if we have (our own, not an external) scrollbar.

Returns:

boolean true if we have our own v scrollbar

index_for_screen_point

public int index_for_screen_point(int y)

This is a convenience function for users to call when they want to know what index is at a given screen cordinate. This function will return -1 if you are out of bounds.

Parameters:

int - y the y coodinate to test

Returns:

int the index of the item at a given point