gui2bitmap

Arguments

idFig

Handle of the graphical figure that must be snapshoted. The figure must be on-screen (off-screen processing is impossible), and must not be docked to any other GUI component.

filename

Single string: pathname of the expected image file. The file extension sets the image encoding: only .png .jpg .gif and .bmp are supported. If the directory of the given pathname does not already exist, it is created. Predefined TMPDIR, SCI, SCIHOME, home... constant paths are supported as heading element in filename.

withBorders

Single boolean (default %F): Set it to %T to include the borders of the figure in its snapshot, including the general window title, menus bar, tools bar, status bar, etc.

parentHandle

Handle of the component on which the gui2bitmap menu must be set. Possible values are:

get(0): a gui2bitmap menu is added to the console's menus bar.
The idFig handle of a figure: Then a gui2bitmap menu is appended to its File first menu.
With Scilab 6, this must be done before plotting anything in the figure (due to the bug 16167).
The idMenu handle of an existing menu, to which the gui2bitmap menu will be appended as a submenu.

borders

Boolean vector with 3 components [left_border, bottom_border, right_border]. This indicates the borders to be grabbed when the withBorders option is used. Default = [%T %T %T].

scale

Single decimal number > 1 : scale of the screen display, in percentage. Default = 100. Other frequent screen settings are 125% and 150%.

Description

gui2bitmap(…) takes a snapshot of the given graphical figure and stores it in an image file.

gui2bitmap(…) is a stand-alone Scilab function using only the JVM embedded in Scilab. It does not require any external software. It aims to replace xs2png(…), xs2jpg(…), xs2gif(…), and xs2bmp(…). Unlike them, it is able to

include uicontrols (if any) in the image, as they appear on the GUI figure ;
snapshot the whole window embedding the figure, including the window borders.

Since it uses the JVM, gui2bitmap() can be used in standard STD Scilab desktop and in No-Window NW (advanced console) modes, but is not available in NWNI batch mode.

gui2bitmap("setMenu", parentHandle)

adds a menu to the console, or a submenu to a given figure (to its File menu) or an existing menu, according to the parentHandle value.

Before calling gui2bitmap(), the file explorer is opened and prompts the user to choose the filename and directory of the image file.

When the menu is added to the console, gui2bitmap() actions apply to the active figure, that is blinked before processing.

This command is ignored in NW execution mode.

gui2bitmap("setScale", scale)

sets the screen display scale, as configuration parameter. The value is recorded in the file SCIHOME/gui2bitmap_preferences.xml and is used by gui2bitmap() for all forthcoming calls and Scilab sessions.

gui2bitmap("setBorders", borders)

indicates which window borders must be include in the image when gui2bitmap() is called with the withBorders option. The borders boolean vector is recorded as configuration parameter in the file SCIHOME/gui2bitmap_preferences.xml and is used by gui2bitmap() for all forthcoming calls and Scilab sessions.

This setting is useful for instance to trim transparent borders, with [%F %F %F].

No variable named File, Robot, or Rectangle must exist anywhere in the calling level of gui2bitmap() (and in the upper callers, if any).

Examples

// Generate a nice GUI (from demos)
exec("SCI/modules/gui/demos/uicontrol_plot3d.dem.sce",-1);
//
f = gcf();
f.axes_size = [650 400];
sleep(500)
figGUI = "TMPDIR/gui2bitmap/gui2bitmap.png";

// Export the window
gui2bitmap(f, figGUI, %t)   // with window borders

// Let's see the image
winopen(figGUI)
sleep(500)

// Now without the window borders:
gui2bitmap(f, figGUI)
winopen(figGUI)

close(f);
rmdir(fileparts(figGUI));

.

Finally, let's trim the left, bottom and right borders, but keep the heading area and the status bar at the bottom :

xdel(winsid())
exec("SCI/modules/gui/demos/uicontrol_plot3d.dem.sce",-1);
f = gcf();
f.axes_size = [650 400];
f.infobar_visible = "on";
figGUI = "TMPDIR/gui2bitmap/gui2bitmap.png";

gui2bitmap("setBorders", [%F %F %F])
gui2bitmap(gcf(), figGUI, %t);

// Let's see the image
winopen(figGUI)

// Restore the default borders setting
gui2bitmap("setBorders", [%T %T %T])

Let's add a gui2bitmap menu to the console, and use it:

xdel(winsid())
plot
exec("SCI/modules/gui/demos/uicontrol_plot3d.dem.sce",-1);

// Two graphical windows are now defined. The active one is the plot3d GUI.

gui2bitmap("setMenu",get(0));
// Look at the console's menu bar => gui2bitmap menu.
// Use it and see how it proceeds.

Author

Samuel GOUGEON

History

Version	Description
1.0	2019-08-02 : First release
1.1	2019-08-05 : On Windows, any graphical window that is partly shifted off-screen is now managed. 3 bugs fixed.
1.2	2019-08-09 : gui2bitmap() now works as well on Linux and MacOS. "setMenu", "setBorders", and "setScale" syntaxes added. Unitary tests added.