/ chips4.11 / ahelp / DepthControl.html

Jump to: Description · Setting An Object's Depth · Retrieving an Object's Depth · Listing Objects at a Depth · Changing Position within a Depth · Hiding/Displaying a Depth · Reindexing and Collapsing Depths · Bugs · See Also

AHELP for CIAO 4.11 ChIPS v1

depthcontrol

Context: concepts

Synopsis

Depth contols the rendering order and appearance when objects overlap.

Description

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.

Setting An Object's Depth

Initial Depth Value

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.

Changing an Exisiting Object's Depth

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,] attributes)
set_colorbar([id,] attributes)
set_contour([id,] attributes)
set_curve([id,] attributes)
set_histogram([id,] attributes)
set_image([id,] attributes)
set_label([id,] attributes)
set_line([id,] attributes)
set_plot([id,] attributes)
set_point([id,] attributes)
set_region([id,] attributes)

For example:

set_label(["depth", 50])

set_label({"depth": 50})

set_label("depth=50")

l = ChipsLabel()
l.depth = 50
set_label(l)

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)

For example:

set_line_depth(15)
set_line_depth("line2", 11)
id = ChipsId()
id.plot = "plot2"
id.line = "line1"
set_line_depth(id, 55)

Retrieving an Object's Depth

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_label('lbl1', '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.plot = 'plot1'
id.line = 'line1'
get_line_depth(id)

Listing Objects at a Depth

The info_depth command provides a means of seeing what objects are at various depths.

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.

Changing Position within a Depth

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.

See the shuffle ahelp page, or the object-specific commands - e.g. shuffle_curve and shuffle_image - for more information.

Hiding/Displaying a Depth

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.

Refer to the hide_depth and display_depth ahelp pages for more information and examples.

Reindexing and Collapsing Depths

A depth (and all objects within that depth) can be changed to a different depth value with the reindex_depth command. To change - or merge - multiple depth levels to a new value, use the collapse_depths command.

Bugs

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.