P-GUIDE Documentation
PUI-Based Graphical User Interface Designer
P-GUIDE comes up in three OpenGL windows. The first window is the
Main window in which the user arranges the widgets of his graphical user
interface. The second window is the Widget window which contains
one button for each PUI widget class. The third window is the Status
window which allows the user to see and control various widget and window
parameters in the main window.
The basic concept of P-GUIDE is that the user will click on a button
in the Widget window and then click in the Main window to create a widget
for his GUI. He will then use the Status window to modify the settings
of that widget. The Main window reflects the changes he makes in
real time. When the user has created as many widgets as he likes,
he clicks on the "Write Window Code" button in the Status window and P-GUIDE
will write a file of C++ code which implements the GUI using OpenGL, GLUT,
and PUI.
P-GUIDE is offered to the PLIB community under a GNU Public License
(GPL). Users are free to modify the source code as they see fit but
must offer their changes back to the community.
GUI Window Control
The user may size, position, color, and name his window by using the input
box widgets at the top of the Status window. All the changes except
the window position are reflected immediately in the Main window.
The user may also change the size of his window by clicking on an edge
of the window and dragging on it. Any widgets which the user has
already defined and placed in the window will remain stationary while the
window is being resized; this means that if the user drags the left-hand
edge of the window to change its width, the x-coordinates of the widgets
will change. (The user is cautioned against moving his mouse off
one side of the window, dragging it around the outside of the window, and
clicking on the opposite side of the window from the outside. Due
to a limitation in the windowing system this will reposition the widgets
in the window incorrectly.)
Placing Widgets
To place a widget in the GUI, the user clicks on that widget's button in
the Widget window and then clicks in the Main window. The new widget
will be placed in the Main window with its lower left-hand corner at the
mouse position. The widget will have an initial size of 90 pixels
wide by 20 pixels high.
If the user wants to place more than one widget of the same type in
his GUI, he can press the Control key when he clicks on that widget's button
in the Widget window. He will then click in the Main window once
for each widget of the given type that he wants to create. Pressing
the Escape key or clicking on another widget's button in the Widget window
will deactivate the button.
A widget which has just been placed or has just been clicked on by
the mouse is called the Active widget. It is surrounded by a black
line.
Widget Settings
The user can control the following settings of his widget from controls
in the Status window:
-
Name (the name of the variable which is the pointer to the widget in the
program)
-
Position
-
Size
-
Legend text and position
-
Label text and position
-
Callbacks
The user may also modify the size and position of his widgets directly
in the Main window. To change the size, he clicks inside the widget
within five pixels of the edge and then drags the mouse to extend the widget.
To change the position he clicks inside the widget away from the edges
and drags the mouse.
The user may also move the Active widget one pixel at a time by pressing
the four arrow keys. Holding the Control key while pressing the arrow
keys will move the Active widget ten pixels at a time.
Widget Visibility
There are obviously times when the user will want to draw more than one
widget in the same place in the GUI and only show them one at a time.
To allow this capability the Status window has a button box which controls
whether the widget in the Main window is visible or not. To hide
a widget the user simply clicks on the "Visible" button box. If he
then clicks on the "Visible" button box again the Active widget will reappear.
If the user selects another Active widget, there is no simple and direct
way to make the single hidden widget reappear in the main window.
To allow the user to make widgets reappear, the Status window has a
one-shot button labelled "Reveal All Widgets". This makes all the
widgets in the Main window visible again. The user can then select
the widgets he wishes to hide again and make them invisible.
When the program writes the C++ code to create the GUI, the widgets
which are not visible in the Main window are hidden by default.
Widget Layers
Many times the order in which widgets are drawn is of vital importance.
For example, the user may want to fill a window with a frame widget to
provide a pleasing background for the actual widgets of the GUI.
In order to allow this the program assigns each widget in the Main window
a layer number. These layer numbers start at zero and increase.
When the Main window is being drawn, the widgets in lower-numbered layers
are drawn first and the widgets with larger layer numbers are drawn after
(and therefore on top of) them. When the C++ code to create the GUI
is being written, the widgets in the lower-numbered layers are created
first.
Program Controls
Basic program control is provided by the three buttons at the bottom of
the Status window. Clicking on the "Write Window Code" button will
cause a file selector widget to pop up for the user to enter a file name
into which the code is to be written. An entire file is written which
contains the necessary include, window data, a default font definition,
widget variable definitions, GLUT window callbacks, widget callbacks for
each widget, and a complete main program that creates and manages the GLUT
window, initializes PUI, creates the widgets, and calls the GLUT main loop.
(At the moment the widget definition calls are somewhat lacking and the
user will need to modify them before he can compile the code.)
If the user clicks on the "Clear" button, all the widgets in the Main
window will be erased. If the user has changed the window at all
since the last time he wrote code or cleared the Main window, the program
will pop up a box asking if he is sure.
If the user clicks on the "Quit" button, the program will stop.
Again, if there have been changes since the last code writing or clearing,
the program will ask if he is sure.