|AHELP for CIAO 4.5 ChIPS v1||
Depth contols the rendering order and appearance when objects overlap.
Depth control allows the user to specify the depth at which each object is placed within a frame. The default depth of items can be configured such that certain items always appear at different depths. For instance, label annotations can be set to always appear above curves or contours. Alternatively, items can all be set to the same depth so that the order in which they are added dictates how they overlap.
Management of depths includes the ability to reindex a depth (change a depth to a different value), to collapse depths (merge several depths into a single depth), control the visiblity of individual depths, and list all the objects associated with a particular depth. Additionally, methods exist to allow the user to modify the order of objects within each depth.
When objects are created, they are assigned a depth value. The depth to which an object is assigned, along with the order that the objects were added to the depth, determines the rendering order of the frame. Depths are rendered from the lowest depth value greater than 0 to the highest depth value in use. Objects within each depth are rendered, by default, in the order in which they were created. The order may be explicitly changed, as explained in the "Changing Position within a Depth" section.
Each object has a default depth preference value which may be set in the ChIPS resource file or by calling the set_preference function. The value of the preference may be set to "default" or a positive integer value. If the value is default, then default frame depth is used. The value of the frame default is initialized to the value of the preference 'default.depth', but may be modified by using the set_default_depth command. The new setting does not affect the depth of existing objects, only new ones created after the call to set_default_depth.
The depth also may be set when an object is created:
add_label(100, 200, "Source A", "depth=75")
Refer to "ahelp add_<object>" for more information and examples.
Like other object properties, depth may be modified at any time. Currency rules and ChipsId specifications work as they do for other commands; see "ahelp currency" and "ahelp chipsid" for more information.
The object-specific set commands can be used to change the depth:
set_axis([id,] values) set_colorbar([id,] values) set_contour([id,] values) set_curve([id,] values) set_histogram([id,] values) set_image([id,] values) set_label([id,] values) set_line([id,] values) set_plot([id,] values) set_point([id,] values) set_region([id,] values)
set_label(["depth", 50]) r = ChipsRegion() r.depth = 34 set_region(r)
Each of the set accessors has a help file; refer to "ahelp set_<object>" for more information and examples.
The module of advanced ChIPS functions contains attribute-specific methods for changing the depth (refer to "ahelp chips" for information on loading the module):
set_axis_depth([id,] depth) set_colorbar_depth([id,] depth) set_contour_depth([id,] depth) set_curve_depth([id,] depth) set_default_depth([id,] depth) set_histogram_depth([id,] depth) set_image_depth([id,] depth) set_label_depth([id,] depth) set_line_depth([id,] depth) set_plot_title_depth([id,] depth) set_point_depth([id,] depth) set_region_depth([id,] depth)
set_line_depth(15) set_line_depth("line2", 11) id = ChipsId() id.line = "line1" set_line_depth(id, 55)
The get_<object> accessors return all the attribute values of the object type, including depth. To retrieve just the depth value, provide the attribute name and the id or ChipsId of the object.
get_axis([id,] depth) get_colorbar([id,] depth) get_contour([id,] depth) get_curve([id,] depth) get_frame([id,] depth) get_histogram([id,] depth) get_image([id,] depth) get_label([[id,] depth) get_line([id,] depth) get_plot([id,] depth) get_point([id,] depth) get_region([id,] depth]) get_window([id,] depth)
Examples of using get accessors:
get_line('line2') get_label(None, 'depth')
Each of the get accessors has a help file; refer to "ahelp get_<object>" for more information and examples.
The module of advanced ChIPS functions contains attribute-specific methods for retrieving the depth (refer to "ahelp chips" for information on loading the module):
get_axis_depth([id]) get_colorbar_depth([id]) get_contour_depth([id]) get_curve_depth([id]) get_default_depth([id]) get_histogram_depth([id]) get_image_depth([id]) get_label_depth([id]) get_line_depth([id]) get_plot_depth([id]) get_point_depth([id]) get_region_depth([id])
get_label_depth() get_line_depth('line2') id = ChipsId id.line = "line1" get_line_depth(id)
The info_depth command ("ahelp info_depth") provides a means of seeing what objects are at various depths.
info_depth( [ChipsId,] [depth] )
The command returns a string that contains each depth accessed and the objects which are at that depth. A depth has been accessed if an object ever resided at that depth, even if there aren't any objects currently set to that depth.
The "depth" preference in the info command can be set to display the object depth as "d <depth>" within the info listing. By default, info returns all items in the ChIPS hierarchy; "ahelp info" describes other configuration options for the command.
set_preference("info.depth", "true") info()
By default, objects within a depth are ordered chonologically based on when they were added to that depth. The objects are stacked with the oldest item at the back of the list and the newest item at the front of the list.
The shuffle command changes the object's position within the stack. Any given object may be shuffled forward or backward one place in the stack or sent directly to the front or back of the stack.
shuffle([id,] object, manner)
where "manner" is one of the following:
|chips_back||send to the back of the stack|
|chips_front||send to the front of the stack|
|chips_forward||moves one step closer to the front|
|chips_backward||moves one step further back|
There are also object-specific shuffle commands
shuffle_axis([id,] manner) shuffle_colorbar([id,] manner) shuffle_contour([id,] manner) shuffle_curve([id,] manner) shuffle_histogram([id,] manner) shuffle_image([id,] manner) shuffle_label([id,] manner) shuffle_line([id,] manner) shuffle_point([id,] manner) shuffle_region([id,] manner)
Each of the shuffle commands has a help file; refer to "ahelp shuffle_<object>" for more information and examples.
Each depth within a frame may be displayed or hidden, regardless of whether the depth contains any objects. When a depth is hidden, any objects which are located at that depth become hidden as well. They still exist and will be listed in an info command, but do not appear in the window.
The commands to hide and display a depth are:
hide_depth([ChipsId,] depth) display_depth([ChipsId,] depth)
A depth (and all objects within that depth) can be changed to a different depth value with reindex_depth ("ahelp reindex_depth").
reindex_depth([id,] olddepth, newdepth) reindex_depth(100, 50) reindex_depth("frm1", 50, 65)
The collapse_depths command ("ahelp collapse_depths") merges an array of depths into a single new depth. The order in which the depths are specified dictates the order in which the objects are merged into the new depth.
collapse_depths([ChipsId,] old_depths_array, new_depth) collapse_depths([50, 65, 100], 20)
See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.