/ chips4.11 / ahelp / chipsgui.html

Jump to: Description · Selecting a color · Changing axis properties · Moving, resizing, and rotating objects · Object selection · Adding annotations from the GUI · The GUI and ChIPS server lifetimes · Plugin Menu Format · Bugs · See Also

AHELP for CIAO 4.11 ChIPS v1

chipsgui

Context: chips

Synopsis

The ChIPS GUI

Description

Information on how to use the ChIPS GUI is available from the built-in help menu, some of which is repeated below. The GUI capabilities are available however a ChIPS plot is created - whether from the ChIPS shell, Sherpa, or prism.

Bringing up the GUI

The GUI can be launched by right clicking on an existing ChIPS window and selecting "Show GUI", or by running the show_gui command from the ChIPS command line.

ChIPS GUI

The ChIPS GUI allows you to edit the attributes of objects using a GUI rather than the command line. When in "Select" mode, clicking in the ChIPS window will highlight the object under the click (square "handles" will appear at the edges of the object). At this point, selecting the "Edit <Object>" menu item brought up by the right-menu button will create a dialog window which will let you edit the properties of the object. Alternatively, the object can be selected from the object list in the main window of the ChIPS GUI, and its attributes edited from there.

Edits are reflected immediately in the ChIPS window - unless the window.display parameter is False - and can be undone using the undo button, menu item, or command.

Menu options in the ChIPS window

Using the right-mouse button in the ChIPS window brings up the following menu items (some may be disabled depending on the state of ChIPS):

Menu Item	Description
Undo	Calls undo()
Redo	Calls redo()
Edit <Object>	Bring up a window containing the properties of the selected object. No other changes to the ChIPS window or main GUI (if shown) are possible when this dialog is displayed.
Delete <Object>	Deletes the selected object
Shuffle Object	Change the rendering order of the selected object
Annotate	Add an annotation - label, point, line (single or multiple segments, horizontal or vertical), region (polygon, ellipse, box), or colorbar - directly to a plot
Pan	Change to the pan mode
Range	Change to the range mode
Select	Change to the select mode
Print	Brings up the print dialog
Show Gui	Calls show_gui() if the GUI isn't already displayed.

Keyboard use

The keyboard can also be used; when the ChIPS window is active the following key presses are recognized:

Delete - delete the selected object,
Backspace - delete the selected object,
p - change to pan mode,
r - change to range mode,
s - change to select mode,
+ - zoom in,
- - zoom out,
arrow keys - move the selected object.

Default layout

The default layout for the GUI is

 /-------------------------------------------------\
 | Menu Bar                                        |
 |-------------------------------------------------|
 | Tool Bar                                        |
 |-------------------------------------------------|
 | Coordinate Pane         | Properties Pane       |
 |                         |                       |
 |                         |                       |
 |-------------------------|                       |
 | Info Pane               |                       |
 |                         |                       |
 |                         |                       |
 |-------------------------------------------------|
 | Shell/Error Pane                                |
 |                                                 |
 \-------------------------------------------------/

These elements can be removed by using either the "Edit/Gui Configuration" or "View/Show ..." menu items.

The alternate layout

Selecting the "View/Alternate Layout" menu item changes the GUI window to (assuming all elements are being shown):

 /-------------------------------------------------\
 | Menu Bar                                        |
 |-------------------------------------------------|
 | Tool Bar                                        |
 |-------------------------------------------------|
 | Properties Pane         | Info Pane             |
 |                         |                       |
 |                         |                       |
 |-------------------------|                       |
 | Coordinate Pane         |                       |
 |                         |                       |
 |                         |                       |
 |-------------------------------------------------|
 | Shell/Error Pane                                |
 |                                                 |
 \-------------------------------------------------/

The Properties Pane

This area is used to display the properties of the selected object (either by selecting an object in the Info Pane or by clicking on the object in the ChIPS window when the mode is set to Select). If the object has many attributes - such as a curve or axis - then the display will use a tabbed interface to display related components.

The Info Pane

The Info Pane is used to show the current objects that have been created. The default appearance ("Tree") follows that used by the info() command but this can be changed to an icon mode by using the right-mouse button within the area to select the "Icon" mode. Selecting an item in this area will display the object's properties in the Properties Pane. If the mode is set to "Select" then the object will also be highlighted in the ChIPS window (by displaying the cyan squares at the edges of the object).

Arrow keys - up and down in Tree mode and left and right in Icon mode - can be used to change the selected object.

When in Tree mode, typing a phrase in the info pane will display a text box and jump to the first object that matches the text. This can be particularly helpful when a large number of objects have been created. The search is progressive so "ax" will take you to an Axis object and then you can add 1 to get to the axis called "ax1" or use the up and down arrow keys to jump between those items that match the current search term. The search is case insensitive.

The Coordinate Pane

The coordinate pane lists the currently-selected plot and X/Y axis pair, which you can change using the drop-down menu. It also lets you change the axis limits, by entering in values or using the "auto" button to use the maximum data range of all the objects in the plot. The axis scale (logarithmic or linear) and direction can also be changed here by using the "log" and "flip" buttons respectively.

The top-right area of this pane contains a simple display showing the data range of the current plot as a black rectangle and the display range as the blue rectangle. Clicking and dragging within this area will scroll the data around, and using the scroll wheel on your mouse will zoom into or out of the plot.

The Tool Bar

The tool bar has two sections: on the left are buttons that let you change the interaction mode when you use the mouse in the ChIPS window, and the right are common options like undo, redo, print, and clear plot (which removes just the selected plot, not the whole visualization like the clear() command does). The display for the buttons can be changed from the default value (both) to just labels or icons using the "Edit/Gui Configuration" menu option.

The Shell/Error Pane

This area of the GUI contains an embedded ChIPS shell, which can be used to enter ChIPS or any other Python command, and an Errors tab which is used to display certain error messages from ChIPS commands.

Errors caught by the GUI - such as trying to delete an axis when it is displaying an object such as a curve or label - will be displayed in the Error tab. The label of the tab changes color to red to indicate the presence of an error; selecting the tab will display the error message and reset the label to its normal color.

Interaction Modes

Mode	Description
pan	This allows you to change the limits of a plot by pressing (and holding) then left mouse button and then dragging the contents around. If you double click then the mode will be changed to select; you will still be able to change the plot limits but clicking on an object will select it.
range	The range mode acts as if you had called pick_limits(); click and drag will select an area of the plot to zoom in to.
zoom	The zoom mode provides an interactive zoom mode; scrolling the mouse wheel will zoom into or out of the plot.
select	The select mode lets you drag the plot around, as with the pan mode, but clicking on an object will highlight it in both the ChIPS window (squares will be displayed at the edges of its bounding box) and in the GUI. For objects that can be moved or re-sized (such as labels, plots, and axes) then dragging the handles or using the arrows on your keyboard will change the object. Labels and points can also be rotated by dragging the marker that appears above the bounding box of the label.

In many cases there is no difference between the pan and select modes; they are useful when an object fills the plot area - for example an image - since in select mode you can only drag the plot limits around by selecting a part of the plot with no object in it.

In all modes you can use the mouse scroll wheel or the + and - keys to zoom into and out of the plot.

The Plugin Menu

The GUI contains a PlugIn menu which can be used to provide extra functionality by calling external Python code. If the file .chips.funcs is found in your home directory then it will be used to set up the options in this menu. The format of the file is described in the "Plugin Menu Format" section below.

Selecting a color

The color widgets allow you to chose a new color either from a predefined list of colors or using a color wheel. Selecting the downwards triangle will display a list of color names, including the special "default" color setting. Selecting the color bar will bring up the standard GtK+ color wheel where you can choose from any of the colors displayable by ChIPS.

When showing the predefined list of colors, the currently selected color (if there is one) will be highlighted. This display also indicates what color the "default" color represents.

Changing axis properties

As you may wish to use the same settings for both axes, the Axis properties section includes on the first ("Axis") tab, the option to change both axes or just the selected one by changing the setting of the "Changes applied to:" widget. This option does not apply to all settings (e.g. the label is not shared between axes).

The "Axis" tab contains the most-commonly changed attributes of the axis; these are also repeated in the appropriate tab. For example, the text of the axis label can be changed on this tab and in the "Label" tab, but the font settings are only available in the latter.

Moving, resizing, and rotating objects

The small square "handles" that appear when an object is selected can be used to move, resize, or rotate some objects. Once an object has been highlighted, pressing the 'delete' key will delete it.

Moving an object

If the object can be moved then the mouse pointer will change from an arrow when moved over the object. Pressing the mouse down and dragging the object will then move it around. You can also use the arrow keys on your keyboard to move the object once it is selected.

Re-sizing an object

If the object can be re-sized then the mouse pointer will change when it is moved over the handles. Dragging these handles will resize the object.

Plots can be re-sized in this way, but care needs to be taken if the plot contains axes since they are drawn on top of the plot. Selecting an axis will just draw three handles, along the axis, whereas selecting a plot border will draw eight handles around the whole plot.

Rotating labels and points

Labels and points can be rotated using the small handle that appears above the other handles. Moving the mouse over this handle changes the pointer to two curved arrows; dragging this handle around will then change the angle of the object.

Object selection

Highlighting an object

The default behavior is to add handles around an object when it is selected. This can be changed to "blink" the object (and any of it's children) by selecting the "Highlight on Selection" option from the General tab of the preferences dialog displayed by the "Edit/Gui Configuration" menu option.

Changing the colors of the selection handles

The "Selection Color" option on the same tab allows you to change the color used to draw the handles of a selected object.

Adding annotations from the GUI

Annotations - labels, points, lines, regions, and color bars - can be added directly from the GUI using either the Annotate menu from the main GUI or the menu created by the Right-Mouse Button in the ChIPS window. Once the annotation has been created, it is automatically selected, so you can use the GUI to adjust its properties, including dragging it around or using the delete key to delete it.

Label

Selecting a position in the ChIPS window will let you type in the label directly (a rectangle surrounding the label is displayed). To stop the process press return.

Point

Select the position where you want the point to appear.

Lines

There are three types of line:

Name	Description
Polyline	Click at each vertex, using escape to exit the process.
Horizontal line	Click at the position where the line should appear.
Vertical line	Click at the position where the line should appear.

Regions

There are three types of regions:

Name	Description
Polygon	Click at each vertex, using escape to exit the process. The polygon is automatically closed for you, so you do not need to make the first and last points overlap. The system will refuse to create a vertex if it would cause the region to intersect itself.
Ellipse	Click and drag to create the ellipse (start at one corner and drag to the opposite corner).
Box	Click and drag to create the rectangle (start at one corner and drag to the opposite corner).

The GUI and ChIPS server lifetimes

When you start a ChIPS session then the first plot you create will start a new ChIPS server (unless you have used the connect() command to use an existing server). As the GUI also creates a connection to the ChIPS server, exiting the ChIPS session when a GUI is still running will not destroy the visualization (since there is still a program connected to the server). Exiting the GUI (e.g. via the Quit option in the File menu) will lead to the ChIPS visualization being closed down.

Plugin Menu Format

The file is executed as a Python script so needs to be a valid Python format and load any necessary Python modules. The docstring of each function is searched and those that match the following pattern are used to fill up the menu items:

menu title = ...

where ... is used as the label in the Plugin Menu.

The following script gives an example menu item which will set all the *.color entries of the current plot red:

import pychips.all as chips

def paint_it_red():
    """
    menu title = Make everything red
    """

    try:
        chips.open_undo_buffer()
        chips.set_cascading_property(chips.chips_plot, "all.color", "red")
    except:
        chips.discard_undo_buffer()
        raise()
    else:
        chips.close_undo_buffer()

The wrapping of the set_cascading_property call by an open/close undo buffer is to ensure that undo/redo treat this as a single command. In this example it is not necessary, since we only run a single ChIPS command, but is left in for didactic purposes.

Error Handling for the plugin code

Any errors raised whilst running the function will be displayed in the terminal that started the ChIPS server (if one exists).

Bugs

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