Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/chips/ahelp/set_frame.html
AHELP for CIAO 4.11 ChIPS v1

set_frame

Context: frames

Synopsis

Modifies the attributes of an existing frame.

Syntax

set_frame(attributes)
set_frame(id, attributes)

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item, or a string containing the name of the object.
attributes Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The set_frame command sets the specified attributes to the provided values. The modified frame becomes current. Multiple frames may be modified with a single command by setting the currency to "all".

Customizing the Frame

There are several attributes that control the characteristics of frames. The set_frame command may be used to modify the attribute values of an existing frame at any time during a ChIPS session. See "ahelp attributes" and "ahelp setget" for more general information.

If multiple attributes are being set simultaneously and one of them fails, the entire command will fail and the frame will not be modified.

Please see the section "Frame Preferences and Attributes" below the examples for a list of the frame attributes.

Frame Mode

The frame mode is not controlled by an attribute of the set_plot command. It is specified with set_framemode command.

The arguments of the command are:

set_framemode(mode)
set_framemode(id, mode)

If the frame mode is "placed", then the frame is located at the specified coordinates within the window. If the frame mode is "single", the frame takes up the entire window. If the mode is changed to "placed", the frame is then displayed at the specified coordinates. For example

chips> set_framemode("placed")

Advanced Functions

The module of advanced ChIPS functions contains other commands for setting attribute values (refer to "ahelp chips" for information on loading the module):

set_frame_bgcolor
set_frame_border_color
set_frame_scale
set_frame_transparency

Examples

Example 1

chips> set_frame(["bgcolor", "navy"])

Using attribute/value pairs, set the frame background color to navy.

Example 2

chips> set_frame({"bgcolor": "navy"})

This is a repeat of the previous example, using a dictionary rather than a list to define the attributes to change.

Example 3

chips> frm = ChipsFrame()
chips> frm.border.color = "blue"
chips> frm.border.visible = True
chips> set_frame("frame1", frm)

Populate the "frm" structure with attribute values, then use it to set frame1 to have a blue border


Frame Preferences and Attributes

The attributes associated with frames are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_frame() command. To change the frame preference settings prepend "frame." to the attribute name.

Attribute Description Options Default Set?
aspect Maintain the aspect ration of the frame when changing tiling modes? see the Booleans section of "ahelp chipsopt" true Yes
bgcolor Background color of the frame. name or hex; see the Color section of "ahelp chipsopt" default Yes
border.color Color of the border denoting the location of a frame in the window. name or hex; see the Color section of "ahelp chipsopt" default Yes
border.visible Boolean flag indicating if the frame border should be visible. see the Booleans section of "ahelp chipsopt" false Yes
mode how the frame is displayed in the window placed or single placed No
scale If set to true, all labels inside a window are rescaled as the window size is altered. see the Booleans section of "ahelp chipsopt" true Yes
stem Default stem for newly created frames An alpha-numeric character sequence that does not contain a space frm No
transparency Boolean flag indicating whether any object behind the frame is visible. see the Booleans section of "ahelp chipsopt" false Yes

Bugs

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

See Also

concepts
setget
frames
add_frame, arrange_frames, blink_frames, current_frame, delete_frame, display_frame, get_frame, hide_frame, move_frame, next_frame, reposition_frame, tile, view_placed_frame, view_single_frame
utilities
erase, get_object_count, set_current