currency

Context: concepts

Synopsis

Currency is the notion of which objects in a ChIPS visualization are currently being used (e.g. having their attributes changed).

Description

ChIPS uses a hierarchical approach to constructing plots. Any number of windows may exist, and each window may contain zero or more frames. The frames contain plots. The plots contain any axes, curves, images, contours, histograms and annotations, such as regions, lines, points, labels, and color bars. Graphically, the layout looks like:

WINDOWS--------------------------+
|   FRAMES-------------------+   |
|   |   PLOTS -----------+   |   |
|   |   |   AXES         |   |   |
|   |   |   COLORBARS    |   |   |
|   |   |   CONTOURS     |   |   |
|   |   |   CURVES       |   |   |
|   |   |   HISTOGRAMS   |   |   |
|   |   |   IMAGES       |   |   |
|   |   |   LABELS       |   |   |
|   |   |   LINES        |   |   |
|   |   |   POINTS       |   |   |
|   |   |   REGIONS      |   |   |
|   |   +----------------+   |   |
|   +------------------------+   |
+--------------------------------+

Since there may be multiple instances of any object, ChIPS internally tracks which objects are currently being accessed. Those objects being accessed are considered "current"; the overall state of the system is referred to as "currency."

Each object maintains a notion of which of its child objects are current. For instance, if there are two windows and each contains two frames, ChIPS records whether the current window is win1, win2, or both ("all"). Within each window, it also keeps track of the current frame: frm1, frm2, or all frames.

How an Object Becomes Current

There are four ways that an object becomes current: addition, modification, explicit setting, and deletion.

Addition: creating a new object. ChIPS automatically makes a newly-created object current. The object remains current unless currency is changed by one of the other methods.
Modification: changing the properties of an existing object make that object current. A ChipsID object can be used to override currency and modify the attribute values of a non-current object. Refer to "ahelp attributes" for more information on configuring object properties.
Explicit Setting: there are a set of current_<object> commands (e.g. current_curve, current_frame) that explicitly change the currency of an object type.
Deletion: when an object is deleted, the parent object sets the last object of that type that was created to be current (not the one that was most recently current)

Use of All

The value "all" is used to set all children of an object to be current. All objects may be current and one object may be current, but you cannot create a subset of currency. For instance, if you have three curves, it is not possible to specify just two of them as current.

What Objects are Current

The info_current command provides a means of seeing what objects are current in the ChIPS session. The listings start at the window level and proceed down through frames and plots. Objects that are not current are omitted from the list. The info_current help file ("ahelp info_current") has more information and examples.

info_current()

The "current" preference in the info command can be set to display current items in reverse video 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.current", "true")
info()

Setting Currency

As mentioned, explicitly setting currency can be achieved via the current_<object> commands: current_axis, current_colorbar, current_contour, current_curve, current_frame, current_histogram, current_image, current_label, current_line, current_plot, current_point, current_region, current_window.

Each of the commands has a help file; refer to "ahelp current_<object>" for more information and examples.

There is also a generic set_current command ("ahelp set_current") which requires the object type to modify, such as chips_window or chips_curve (see the list in the Object Type section of "ahelp chipsopt"):

set_current(chips_window, "win3")

Bugs

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