[Home]Gscreen Customization

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org

This is under construction and will likely be slightly out of date since Gscreen is still being developed
This is rapidly evolving...:
1. Intro
1.1. What's a GLADE file do?
1.2. PyGTK, that's a funny name
1.3. GladeVCP
2. Overview
3. Hey, I can build a GladeVCP panel! What about Gscreen?
4. Building a simple test screen
5. Handler file example
6. What does Gscreen do when it starts up?
7. Other examples

1. Intro

Gscreen borrows heavily from GladeVCP.
GladeVCP uses the GTK widget editor GLADE to build virtual control panels (VCP) by point and click.
Gscreen combines this with python programming to create a user screen (GUI) for running a CNC machine
Which is great, right? As long as you like the screen I built it is - which has got to be right cause it's perfect :)
Well, OK, you have a special machine and you want some buttons and status LEDs - no problem, that's what GladeVCP is for and Gscreen supports it.
But GladeVCP is restricted to positions on the screen that were made for embedding, and you want the button on the left side, damn it!
Hmmm, well, GladeVCP uses the GLADE editor to build the panels and so does Gscreen - so why don't we just use the editor to edit Gscreen?
Well, that is the first level of real customisation of Gscreen!
So the first three you need to know something about are [GLADE] (the editor), [PyGTK] (the widget toolkit), and [GladeVCP] (LinuxCNC's connection to GLADE/PyGTK)
You must know how to use the GLADE editor, PyGTK is the widget toolkit so you need to know what the widgets are and can do, GladeVCP has some special widgets added just for LinuxCNC
And if you were wondering, a widget is just the generic name used for the buttons, sliders, labels, etc. of the PyGTK toolkit.

1.1. What's a GLADE file do?

Hey, didn't you read the link I showed you?
A GLADE file is a text file organized in the XML standard ( Don't worry about that ) that describes the layout and the widgets of the screen
PyGTK uses this file to actually display and react to those widgets.
The GLADE editor makes it relatively easy to build and edit this file
You must use the GLADE editor that uses the GTK2 widgets. Ubuntu 12.04 uses the newest GLADE editor that uses GTK3 widgets.
In that case you must download the older GLADE editor from their repository

1.2. PyGTK, that's a funny name

PyGTK is the python binding to GTK - That clear it all up???
OK, GTK really is the one that displays everything, it's programmed in a language called C.
PyGTK uses a language called Python to interact with GTK. Python is much easier/faster to work with then C

1.3. GladeVCP

GladeVCP binds LinuxCNC, HAL, PyGTK and GLADE all together.
LinuxCNC requires some special widgets so GladeVCP supplies them. Many are just HAL extensions to existing PyGTK widgets
GladeVCP creates the HAL pins for the special widgets described in the GLADE file.
GladeVCP also allows one to add python commands to interact with the widgets, to make them do things not available in their default form
If you can build a GladeVCP panel you can customise Gscreen

2. Overview

There are two files that can be used, individually or in combination to add customizations.
Local glade files and handler files
Normally Gscreen uses the stock GLADE file and possibly a handler file (if using a sample 'skin')
You can specify Gscreen to use 'local' Glade and handler files.
Gscreen looks in the folder that holds all the configuration files for the config you selected.

If present, local glade files in the config folder will be loaded instead of the stock GLADE files
Local GLADE files allow you to use your customized designs rather then the default screens.
There is a switch in the INI file to set set the base name: -c name so Gscreen looks for MYNAME.glade and MYNAME_handler.py. HAL pins will start with this name too.

You can now tell Gscreen to just load the glade file and not connect it's internal signals to it - This allows gscreen to load any GTK builder saved glade file
This means you can display a completely custom screen, but also requires you to use a handler file.
Gscreen uses the GLADE file to define the widgets, show it can show and interact with them. Many of them have specific names, others have GALDE given generic names.
If the widget will be displayed but never changed then a generic name is fine.
If one needs to control or interact with the widget then a hopefully purposeful name is given (all names are unique).
If you change the name of a widget, Gscreen won't be able to find it. At best this makes the widget not work anymore at worst it will cause an error when loading
Widgets can also have signals defined for them in the GLADE editor. It defines what signal is given and what method to call
Gscreen's default screens don't use many signals defined in the editor, it defines them in the python code.
If you move (cut and paste) a widget with signals, the signals will not be copied. You must add them again manually.

A handler file is a file containing python code, which Gscreen adds to it's default routines.
A handler file allows one to modify defaults, or add logic to a Gscreen skin without having to modify Gscreen proper.
You can combine new functions with Gscreen's function to modify behaviour as you like. You can completely bypass all of Gscreen's functions and make if work completely differently.
If present a handler file named gscreen_handler.py (or MYNAME_handler.py if using the INI switch) will be loaded and registered
only one file is allowed
Gscreen looks for the handler file, if found it will look for specific function names and call them instead of the default ones.
If adding widgets you can set up signal calls from the GLADE editor to call routines you have written in the handler file. In this way you can have custom behaviour.
Handler routines can call Gscreen's default routines, either before or after running it's own code. In this way you can tack on extra behaviour such as adding a sound

Please see the GladeVCP write-up about the basics to GladeVCP handler files - Gscreen uses a very similar technique

3. Hey, I can build a GladeVCP panel! What about Gscreen?

Gscreen is just a really big complicated GladeVCP panel, with a bunch of python code to control it.
To customize it we need the GLADE file loaded in the GLADE editor.
Use a compiled from source 'master' version of LinuxCNC
open a terminal and cd to the top of the LinuxCNC folder
Set up the environment by entering '. scripts/rip-environment'
now enter 'glade', you see a bunch of warnings in the terminal and the editor should open
The stock Gscreen GLADE file is in: src/emc/usr_intf/gscreen/ sample skins are in /share/gscreen/skins/
This should be copied to a config folder.
Or you can make a clean-sheet Glade file by saving it in a config folder.

OK, you have loaded the stock glade file and now can edit it. The first thing you notice is it does not look in the editor like what it's displayed as.
Gscreen uses some tricks, such as hiding all boxes of buttons except one and changing that one depending on the mode.
The same goes for notebooks, some screens use notebooks with the tabs not shown. To change pages in the editor you need to temporarily show those tabs.

When making changes it is far easier to add widgets then subtract widgets and still have the screen work properly.
Making objects 'not visible' is one way to change the display without getting errors - this won't always work, some widgets will be set visible again.
Changing the names of Gscreen's regular widgets will probably not work well without python code - but moving a widget while keeping the name is usually workable.

Gscreen leverages GladeVCP widgets as much as possible, to avoid adding python code. Learning about GladeVCP widgets is a prerequisite.
If the existing widgets give you the function you want/need then no python code need be added, just save the GLADE file in your config folder.
If you need something more custom then you must do some python programming.
The name of the parent window needs to be window1. Gscreen assumes this name.

Remember, if you use a custom screen option YOU are responsible for fixing it (if required) when updating LinuxCNC.

4. Building a simple test screen


Lets build a simple usable screen.
Build this in the GLADE editor ( if using a RIP package run it from a terminal after using . scripts/rip-environment ):
Things to note:
-The top level window must be called the default name, window1 Gscreen relies on this,
- EMC actions (on the left side selection pallet) end up being hal_actions on the top right panel description (a renaming miss)
-Add actions by clicking the one you want and then clicking somewhere on the window, they don't add anything visual to the window.
-Add all the ones you see on the top right.
-After adding the actions we must link the buttons to the actions for them to work.(see below)
-The gremlin widget doesn't have a default size, so setting a requested size is helpful.(see below)
-The sourceview widget will try to use the whole window, so adding it to a scrolled window will cover this. (This has already been done in the example).
-The buttons will expand as the window is made larger, which is ugly, so we will set the box they are in to not expand (see below).
-The button types to use depend on the emc_action used -eg emc_toggle_action usually require toggle buttons.(Follow the example for now)

In this screen we are using emc_actions to communicate to LinuxCNC the actions we want.
This allows us standard functions without adding python code in the handler file. Let's link the estop toogle button to the estop action
Select the estop toggle button and under the general tab look for 'Related Action' and click the button beside it.
Now select the toggle estop action. Now the button will toggle estop on and off when clicked.
Under the general tab you can change the text of the button's label to describe it's function.
Do this for all the buttons.

Select the gremlin widget. Click the common tab, set the requested height to 100, and click the checkbox beside it.

Click the horizontal box that holds the buttons. Click the packing tab and click 'expand' to 'No'

OK, that's it - we need to save it as tester.glade and save it in sim/gscreen/gscreen_custom/ folder.
Now launch LinuxCNC and click to sim/gscreen/gscreen_custom/tester and start it.
If all goes well our screen will pop up and the buttons will do their job.
This works because the tester.ini tells gscreen to look for and load tester.glade and tester_handler.py.
The tester_handler.py file is included in that folder and is coded just show the screen and not much else.
Since the special widgets directly communicate with LinuxCNC - you can still do useful things.
If your screen-needs are covered by the available special widgets then this is as far as you need to go to build a screen.
If you want something more there are still many tricks available, from just adding 'function calls' to get canned behaviour,
to coding your own python code to customize exactly what you want. But that means learning about handler files.

5. Handler file example

Here is gaxis and its handler file:
upload:gscreen-gaxis1.png upload:gaxis_handler1.png upload:gaxis_handler2.png
There are special functions Gscreen checks the handler file for.

6. What does Gscreen do when it starts up?

Gscreen is really just infrastructure to load a custom GladeVCP file and interact with it.
Originally there was going to be just one customizable 'Skin', later I switched to making Gscreen more general and the handler file control more detailed.

Gscreen starts by reading the options it was started with. It sets the debug mode and sets the optional skin name.
It then checks to see if there are 'local' XML, handler and/or locale files in the config folder - It will use them instead of the default ones (in share/gscreen/skins/)
The main screen is loaded and translations set up.
If present the second screen will be loaded and translations set up.
Optional Audio is initialized if available.
It reads some of the INI file to initialize the units, and the number/type of axes.
It then initializes python's binding to HAL to build a userspace component with the Gscreen name.
GladeVCP's makepins is called to parse the XML file to build HAL pins for the HAL widgets and register the LinuxCNC connected widgets.
Now Gscreen checks for a 'local' handler file in the config folder or else uses the stock one from the skin folder.
If there is a handler file Gscreen parses it, and registers the function calls into Gscreen's namespace.
At this point Glade matches/registers all signal calls to functions in Gscreen and the handler file.
Gscreen checks the INI file for an option preference file name otherwise it uses '.gscreen_preferences'
Now it checks to see if there is a preference function call ('initialize_preferences(self)') in the handler file otherwise it uses the stock Gscreen one.
Checks for classicladder realtime component.
Checks for the system wide GTK theme.
Collects the jogging increments from the INI file.
Collects the angular jogging increments from the INI file.
Collects the default and max jog rate from the INI.
Collects the max velocity of any axes from the INI's TRAJ section.
If there are angular axes then collects the default and max velocity from the INI file.
Collect all the override setting from the INI.
Check if its a lathe config from the INI file.
Find the name of the tool_table,tool editor and param file from the INI.
Check the handler file for keybindings function ('initialize_keybindings(self)') or else use Gscreen stock one.
Check the handler file for pins function ('initialize_pins(self)') or else use Gscreen stock one.
Check the handler file for manual_toolchange function ('initialize_manual_toolchange(self)') or else use Gscreen stock one.
Check the handler file for connect_signals function ('initialize_connect_signals(self)') or else use Gscreen stock one.
Check the handler file for widgets function ('initialize_widgets(self)') or else use Gscreen stock one.
Set up messages specified in the INI file.
Tell HAL the Gscreen HAL component is finished making pins and is ready.
If there is a terminal widget in the screen it will print all the Gscreen pins to it.
Sets the display cycle time based on the INI file.
Checks the handler file for 'timer_interupt(self)' function call otherwise use Gscreen's default function call.

7. Other examples

Here is another screen: it's GTK widgets placed on top of an image file:
The axes DROs in this pic are actual numbers from a running LinuxCNC


LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
This page is read-only. Follow the BasicSteps to edit pages. | View other revisions
Last edited October 26, 2017 11:34 pm by KimK (diff)
Published under a Creative Commons License