figure properties

Description

The figure entity is the top level of the graphics entities hierarchy. This entity contain a number of properties designed to control many aspects of displaying Scilab graphics objects. These properties fall into two categories. Properties that contain information about figure itself and others related to set default values for the children creation.

Figure properties:

children:

This handles represent the vector of the figure's children . Note that all figure children are of type "Axes". Also keep in mind that, when creating a figure entity (using scf command), an Axes entity is simultaneously built too.

figure_position:

This field contains the position in pixel of the graphic window on the screen. This is a vector [x,y] defining the position of the upper-left corner of the window. The position [0,0] is the upper-left corner of the screen.

The initial position of graphic windows is taken from the default figure entity (see gdf). The only exception is when default figure figure_position value is [-1,-1]. In this case, the initial position of graphic windows is automatically set by the windowing system.

figure_size:

Vector [width, height], providing the external size of the graphic window, in screen pixels.

When the figure is docked (to the Scilab desktop, etc), .figure_size holds for the whole docked block and should not be set.

The OS window manager defines some minimal sizes. If sizes smaller than minimal ones are provided, the minimal ones are actually set. On Windows, minimal sizes can be retrieved with --> [getsystemmetrics("SM_CXMIN") getsystemmetrics("SM_CYMIN")] ans = 158. 45.

When a figure is created in .auto_resize="on" mode, the .axes_size value is set as specified, and .figure_size is set accordingly, not the reverse.

axes_size:

Vector [width, height] of sizes of the whole graphical area in the window, in pixels.

This property should not be modified if the figure is docked to the Scilab desktop.

position:

.position = [x, y, graphics_width, graphics_height] or .position = 'x|y|graphics_width|graphics_height' (like '100|150|500|300') is a pseudo-property allowing to set or querry both .figure_position and .axes_size properties in a once.

auto_resize:

Auto-resizing of children axes when the figure is resized.

When the figure is resized by hand or by setting the .figure_size property, and .auto_resize is

"on"	Then the .axes_size is updated and axes contents are zoomed accordingly, without displaying scroll bars.
"off"	Then the .axes_size is kept unchanged. The display scale of children axes is unchanged. If the window gets smaller than axes sizes, some scroll bars are displayed.

viewport:

Position of the visible part of graphics in the panner.

figure_name or name:

This field contains the name of the figure. This name is a character string displayed at the top of the graphics_window. The name can contain a single substring %d which will be replaced by the figure_id. No other instance of the % character is allowed inside the name.

figure_id:

This field contains the identifier of the figure. This is an integer number which is set at figure creation and cannot be changed after.

color_map:

Property which defines the colormap used by this figure. The colormap is a m by 3 matrix. m is the number of colors. Color number i is given as a 3-uple R, G, B corresponding respectively to red, green and blue intensity between 0 and 1.

pixel_drawing_mode:

This field specifies the bitwise operation used for pixel rendering. The default mode is copy. For more details see the pixel drawing mode reference page.

anti_aliasing:

This property controls the anti-aliasing level used to improve graphic quality. If the property is set to "off", anti-aliasing is disable. To enable anti-aliasing, the property must set to either "2x", "4x", "8x" or "16x". In this case, it stands for the anti-aliasing level. For example, "16x" is a higher quality level than "2x". Specifying a higher anti-aliasing level improves image quality but also decreases graphic performances. Please visit the dedicated page to see specific examples.

immediate_drawing:

This property controls the figure display. Its value can be "on" (default mode) or "off". It is used to delay a huge succession of graphics commands (implying several drawings or redrawings). Note that, when using drawlater or drawnow commands, it affects the property value of the current figure (which is respectively turned to 'off' or 'on').

background:

This property controls the figure window background color. It takes as value an index relative to the current colormap.

BackgroundColor

This pseudo-property is a set-only one. It is the same as background, but allows to specify the color as a [r g b] vector of real values of Red Green and Blue intensities in [0,1] like [0.1, 0.5, 0.3], or as a unique equivalent 'r|g|b' string like '0.1|0.5|0.3', using "|" as a separator.

event_handler

A character string. The name of the Scilab function which is intended to handle the events. Note that setting an empty string will disable the event handler. For more information about event handler functions see the event handler functions help.

event_handler_enable

Enable or disable the event handler. Its value must be either "on" or "off".

user_data:

This field can be use to store any scilab variable in the figure data structure, and to retrieve it.

tag:

This field can be use to store a character string generally used to identify the control. It allows to give it a "name". Mainly used in conjunction with findobj().

resizefcn:

This field can be used to store the name of a Scilab function or a Scilab expression as a character string. This character string will be evaluated whenever the user resizes the figure and when the figure is created.

closerequestfcn:

This field can be used to store the name of a Scilab function or a Scilab expression as a character string. This character string will be evaluated whenever the user tries to close the figure using the top-right cross.

When this property is set, the "figure closed" event (-1000) will no more be trapped by the event handler function.

resize:

"on" (default value) allows the user to interactively resize the figure with the mouse. "off" forbids to do it, but still allows using efficiently the .figure_size property.

menubar_visible:

This property controls the figure menubar visibility. Its value can be "on" (default value) or "off".

toolbar_visible:

This property controls the figure toolbar visibility. Its value can be "on" (default value) or "off".

infobar_visible:

This property controls the figure status bar visibility. Its value can be "on" (default value) or "off".

info_message:

Single character string: text displayed in the info bar of the graphic window.

A multi-line message is possible, using ascii(10) as lines separator, as with "Line #1"+ascii(10)+"Line #2". Styling the text is not possible (HTML styles not supported).

visible:

When the figure "dockable" property is "off", setting the "Visible" property affects the whole figure including its window decorations.

When the figure "dockable" property is "on" and the figure is docked with another one inside the same parent window, this field concerns only the figure children (See dedicated part below). If the figure is not docked with another one, then the "Visible" property behaves as if the figure "dockable" property was set to "off".

layout:

This property sets the layout used to dispose the figure children. See layout page for more information about available layouts.

layout_options:

This property sets the options of the layout used to dispose the figure children. See layout page for more information about available options.

icon:

This field can be used to customize the icon of a Scilab figure.

Its value is a character string containing the (absolute or relative to Scilab current working directory. path of the image file containing the icon.

default_axes:

"on" (default value) means that the figure has always a default axes: it is automatically set at the figure creation, or automatically reset when the last axes of the figure is intentionally deleted.

"off" means that

• the newly created figure has no default axes.
• for an existing figure, it is possible to actually delete all its existing axes.

In both cases,

• without any axes, the figure can't be the default target of any plotting instruction. This feature can be used to protect an interactive interface built in a figure (like the demos and the ATOMS ones) from being the default plotting target when there is no other proper opened graphical figures.
• It is still possible to force creating an axes using the newaxes function.

Children's default values:

visible:

{"on"} | "off"

This field sets if the contents of the figure (axes and uicontrols) has to be redrawn. Its value should be "on" or "off".

rotation_style:

{"unary"} | "multiple"

This field is related to the "3D Rot" button. It takes unary as value (default) in the aim to rotate only selected 3D plot. In the other case its value can be multiple : all 3D plots are rotated.

Creation related properties:

Some properties must be set at creation time using the figure function and will be then read-only.

dockable

This property determines if created window can be docked inside Scilab environment. If its value is "on" then the window will have a bar enabling the user to dock/undock it. Else the window will look like a standard OS window. This value can only be set at creation.

menubar

{"figure"} | "none"

This property determines the type of the menubar of the figure. If its value is "none" then the window will not have any menubar until a menu is added using uimenu function. Else the window will be created with default figure menus. This value can only be set at creation.

toolbar

{"figure"} | "none"

This property determines the type of the toolbar of the figure. If its value is "none" then the window will not have any menubar. Else the window will be created with a default figure toolbar. This value can only be set at creation.

Note on default values:

All these listed properties and fields inherit from default values stored in a figure model. These default values can be seen and changed. To do so, use the get("default_figure") command : it returns a graphic handle on the figure model. Note that no graphic window is created by this command. The next created figures will inherit from this model (see example 2 below).

Examples

lines(0) // disables vertical paging

//Example 1
f=get("current_figure") //get the handle of the current figure :
                        //if none exists, create a figure and return the corresponding handle
f.figure_position
f.figure_size=[200,200]
f.background=2
f.children  // man can see that an Axes entity already exists
delete(f);
f=gcf(); // macro shortcut <=> f=get("current_figure")
f.immediate_drawing = "off";
plot2d() // nothing happens on the screen...
f.immediate_drawing = "on";

//Example 2 : default_figure settings
df=get("default_figure") // get the default values (shortcut is gdf() )
// Let's change the defaults...
df.color_map=hotcolormap(128)
df.background= 110 // set background toa kind of yellow (Note that we
                   // are using a color index inside the color_map previously redefined)
scf(122); // creates new figure number 122 with the new default
plot2d()
scf(214);
t=-%pi:0.3:%pi;
plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);

See also

• event handler functions — Prototype of functions which may be used as event handler.
• pixel_drawing_mode — Figure's property setting the RGBwise pixels update mode when drawing
• anti_aliasing — Figure's property smoothing the stair-like aspect when rendering curves
• colormap — using colormaps
• scf — set the current graphic figure (window)
• gcf — Return handle of current graphic window.
• gdf — Return handle of default figure.
• get — Retrieve a property value from a graphics entity or an User Interface object.
• set — set properties of some graphic objects or uimenus or uicontrol interactive components
• axes_properties — description of the axes entity properties
• getsystemmetrics — Retrieves the specified system metric or system configuration setting (Windows only)

History