maptek.vulcan_gui.panel

Interface for building basic Vulcan panels.

To download all the example scripts, click here.

Note

To use any of the method calls from this class, be sure to import the library at the top of your Python script, like this:

from maptek import vulcan_gui

Creating a basic panel

maptek.vulcan_gui.panel(*args, **kwargs)

To use this class, create a panel object by defining an object using the method call vulcan_gui.panel() like so:

pan = vulcan_gui.panel('Panel title')

The above example uses pan as the class object, but it can be named anything you want. You can then use that object when calling any of the vulcan_gui class functions used within a panel. For example, to create a static line on the panel you would write a line of code like this:

pan = vulcan_gui.panel('Panel title') # create a class object named pan
pan.staticline() # assign a static line to the object

If you want to call on a function that is not part of the panel or wish to convey information to the user, then you would call it directly without referencing the panel object. For example, to create a message box you would write something like this:

vulcan_gui.message('This is a message box.')

The minimum code needed to create a panel is the call to create a panel object using panel() and the command to display it using display().

display(self, values=None)→ bool

Important: A panel will not be displayed unless the display() method is explicitly called.

# Filename: gui_panel.py
# Purpose:  Basic code to create a GUI panel.
# Results:  Display basic panel.

from maptek import vulcan_gui

pan = vulcan_gui.panel('Basic Panel')
pan.display()

The title of the panel is passed as an argument: panel('basic Panel').

All objects that you want to include in the panel need to be placed between the panel() and display() method calls. Any action from the user that needs to be captured from responding to the panel (such as clicking a button, entering text into a field, selecting from a drop-down list, etc.) needs to be placed after the display() method call, as shown below.

# Filename: gui_radiobutton.py
# Purpose:  Create a panel showing a choice between 3 radiobuttons.
# Results:  Messagebox showing selection.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.radiobutton(tag='rad_1', prompt='Choice one', bank=0)
pan.radiobutton(tag='rad_2', prompt='Choice two', bank=0)
pan.radiobutton(tag='rad_3', prompt='Choice three', bank=0)
pan.display()

if pan['rad_1']:
    choice = 'One'
elif pan['rad_2']:
    choice = 'Two'
elif pan['rad_3']:
    choice = 'Three'

print(f'You chose {choice}.')

Control elements for user input

These are the basic control elements that allow you to interact with user input.

editbox	checkbox
numberbox	radiobutton
integerbox	colour
fileselector	pattern
combobox	linestyle
filterbox

Explanations of each individual control are shown below.

panel.editbox(self, tag, prompt, defaultVal=None, width=None)

Parameters

tag (string) - variable to hold user's response
prompt (string)
defaultVal (default value as a string)
width (integer)

# Filename: gui_editbox.py
# Purpose:  Create a panel showing an editbox.
# Results:  Panel showing an editbox.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.editbox(tag='editbox_input', prompt='Editbox', defaultVal='Enter text', width=20)
pan.display()

edit = pan['editbox_input']
print(edit)

panel.numberbox(self, tag, prompt, defaultVal=None, width=None)

Only numbers can be entered into this box. The numbers can have up to three decimal places.

Parameters

tag (string) - variable to hold user's response
prompt (string)
defaultVal (double)
width (integer)

# Filename: gui_numberbox.py
# Purpose:  Create a GUI panel showing a numberbox.
# Results:  Number entered into numberbox is printed to the screen.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.numberbox(tag='numberbox_input', prompt='Numberbox', defaultVal=None, width=20)
pan.display()

num = pan['numberbox_input']
print(num)

panel.integerbox(self, tag, prompt, defaultVal=None, width=None)

Only whole numbers can be entered into this box.

Parameters

tag (string) - variable to hold user's response
prompt (string)
defaultVal (integer)
width (integer)

# Filename: gui_integerbox.py
# Purpose:  Create a panel showing an integerbox.
# Results:  Number entered into integerbox is printed to the screen.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.integerbox(tag='integerbox_input', prompt='Integerbox', defaultVal=None, width=20)
pan.display()

intg = pan['integerbox_input']
print(intg)

panel.fileselector(self, tag, prompt, filter, width=None)

Combobox with a built in file filter using wildcard matching.

Parameters

tag (string) - variable to hold user's response
prompt (string)
filter (string)
width (integer)

# Filename: gui_fileselector.py
# Purpose:  Create a panel showing a fileselector.
# Results:  Selection from fileselector is printed to the screen.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.fileselector(tag='fileselector_input', prompt='Fileselector', filter='*.00t', width=20)
pan.display()

file = pan['fileselector_input']
print(file)

panel.combobox(self, tag, prompt, options, width=None)

Parameters

tag (string) - variable to hold user's response
prompt (string)
options (list)
width (integer)

# Filename: gui_combobox.py
# Purpose:  Create a panel showing a combobox.
# Results:  Selection from combobox is printed to the screen.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
list = ['One', 'Two', 'Three', 'Four']
pan.combobox(tag='combobox_input', prompt='Combobox', options=list, width=20)
pan.display()

combo = pan['combobox_input']
print(combo)

panel.filterbox(self, tag, prompt, filter, width=None)

Combobox with a built in filter, using gpan filter strings.

Parameters

tag (string) - variable to hold user's response
prompt (string)
filter (string)
width (integer)

# Filename: gui_filterbox.py
# Purpose:  Create a panel showing a filterbox.
# Results:  Selection from filterbox is printed to the screen.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.filterbox(tag='filterbox_input', prompt='Filterbox', filter='*.00t', width=20)
pan.display()

filter = pan['filterbox_input']
print(filter)

panel.checkbox(self, tag, prompt, checked=False)

Parameters

tag (string) - variable to hold user's response
prompt (string)
checked (bool: False=unchecked; True=checked)

# Filename: gui_checkbox.py
# Purpose:  Create a panel showing 3 checkboxes.
# Results:  State of each checkbox is printed to the screen.
#           0 = unchecked; 1 = checked

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='checkbox_1', prompt='Checkbox one', checked=False)
pan.checkbox(tag='checkbox_2', prompt='Checkbox two', checked=False)
pan.checkbox(tag='checkbox_3', prompt='Checkbox three', checked=False)
pan.display()

check_1 = pan['checkbox_1']
check_2 = pan['checkbox_2']
check_3 = pan['checkbox_3']
print(check_1, check_2, check_3)

panel.radiobutton(self, tag, prompt, initial=False, bank=0)

Radiobutton to pick one of several options. Only one tag per bank will return ‘1’.

Parameters

tag (string) - variable to hold user's response
prompt (string)
initial (bool: False=unselected; True=selected)
bank (integer designating the group a radiobutton belongs to.)

# Filename: gui_radiobutton.py
# Purpose:  Create a panel showing a choice between 3 radiobuttons.
# Results:  Messagebox showing selection.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.radiobutton(tag='rad_1', prompt='Choice one', bank=0)
pan.radiobutton(tag='rad_2', prompt='Choice two', bank=0)
pan.radiobutton(tag='rad_3', prompt='Choice three', bank=0)
pan.display()

if pan['rad_1']:
    choice = 'One'
elif pan['rad_2']:
    choice = 'Two'
elif pan['rad_3']:
    choice = 'Three'

print(f'You chose {choice}.')

panel.colour(self, tag, prompt, defaultVal=None)

Selector for colour using Vulcan colour palette. Returns the colour index as an integer.

Example script below.

Parameters

tag (string) - variable to hold user's response
prompt (string)
defaultVal (integer)

panel.linestyle(self, tag, prompt, style=None, thickness=None)

Selector for linestyle using Vulcan linestyles. Returns [line style, line thickness] as a list.

Example script below.

Parameters

tag (string) - variable to hold user's response
prompt (string)
style (integer)
thickness (integer)

panel.pattern(self, tag, prompt, defaultVal=None)

Selector for pattern using Vulcan patterns. Returns the pattern index as an integer.

Parameters

tag (string) - variable to hold user's response
prompt (string)
defaultVal (integer)

# Filename: gui_colourLinePattern.py
# Purpose:  Create a panel showing style selectors.
# Results:  Display selected panel values on screen as a dictionary.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")

pan.begin_block(True, 'Select properties')
pan.colour(tag='colour', prompt='Colour')
pan.linestyle(tag='line', prompt='Linestyle')
pan.pattern(tag='fill', prompt='Pattern')
pan.end_block()
pan.display()

dict = pan.get_values()
print(dict)

Formatting the layout of the panel

There are a number of method calls that can be used to format the layout of your panel. By default, the first control element will be positioned in the upper left corner of the new panel. Each additional control element will be positioned directly below the previous one. However, by using the following method calls you can customise the look of your panel, as well as disabling some control elements until certain conditions have been fulfilled.

begin_block	statictext
end_block	begin_indent
pan_if	end_indent
pan_else	begin_same_line
pan_endif	end_same_line
staticline	skip_line
get_values	save_spec
set_values	load_spec

panel.begin_block(self, border=False, title='')

panel.end_block(self)

Creates a new area on the panel with optional border and title.

Parameters

border (True or False)
title ('string')

Tip

Blocks are often used to group elements together that share a common theme. For example, a series of radiobuttons may be grouped together to indicate that they are all part of the same selection.
Although the title of a block is optional, it is often used to provide instructions regarding what to do with the contents of the block.

If the block border is set to Falsethen neither the title nor the border will be displayed on the panel, as shown in the example below.

All elements contained inside the block need to be placed between the begin_block() and end_block() method calls.

Since a container will try to align all the elements contained inside of it, the results can sometimes be unexpected. Blocks can be used to help align things when each element is placed in its own block.

# Filename: gui_begin_block.py
# Purpose:  Create a GUI panel showing 2 frame blocks, one with border, one without border.
# Results:  Display panel.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")

pan.begin_block(border=True, title='Block with border')

pan.radiobutton(tag='rad_1', prompt='Choice one', bank=0)
pan.radiobutton(tag='rad_2', prompt='Choice two', bank=0)
pan.radiobutton(tag='rad_3', prompt='Choice three', bank=0)
pan.end_block()

pan.staticline()

pan.begin_block(border=False, title='Block without border')

pan.radiobutton(tag='rad_4', prompt='Choice one', bank=0)
pan.radiobutton(tag='rad_5', prompt='Choice two', bank=0)
pan.radiobutton(tag='rad_6', prompt='Choice three', bank=0)
pan.end_block()

pan.display()

panel.pan_if(self)

panel.pan_else(self)

panel.pan_endif(self)

Using 'if' statements within panels makes the next element conditional on the previous element.

# Filename: gui_pan_if.py
# Purpose:  Create a panel with a checkbox, static text, and an editbox.
# Results:  Basic panel using if statement.
#           If checkbox = True, then editbox is enabled and static text is disabled.
#           If checkbox = False, then editbox is disabled and static text is enabled.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='check', prompt='Use Alternative Value', checked=False)

pan.pan_if() # editbox will only be enabled if checkbox is selected.
pan.pan_else()
pan.statictext('Value = 100')
pan.pan_else()
pan.editbox(tag='input', prompt='Alternative value', defaultVal='Enter text', width=20)
pan.pan_endif()
pan.display()

Figure 1: Checkbox not selected, so condition fails.

Figure 2: Checkbox selected, so condition fulfilled.

panel.staticline(self)

Line drawn across panel.

# Filename: gui_staticline.py
# Purpose:  Create a panel showing a fileselector and static text with static line in between.
# Results:  Message box showing selection.

from maptek import vulcan_gui

pan = vulcan_gui.panel('Basic Panel')
pan.fileselector(tag='fileselector_input', prompt='Fileselector', filter='*.00t', width=20)
pan.staticline()
pan.statictext('Static text below line.')
pan.display()

selection = pan['fileselector_input']
message = 'You selected ' + selection
vulcan_gui.message(message)

Note

A static line will extend to fill the width of the block it is in. Therefore, the width of the static line may not extend across the entire panel unless an element has been added that also extends the width of the panel.

panel.begin_indent(self, indent=1)

panel.end_indent(self)

Indent fields a set amount. All objects placed between begin_indent() and end_indent() will be affected.

Traditionally, panels rarely indent more than 2 or 3 spaces. However, you can have as many indents as you need and the distance will be limited by the width of your monitor. The spacing of each indent is approximately the width of one capital letter.

Parameters

indent (number of spaces to indent)

# Filename: gui_begin_indent.py
# Purpose:  Create a panel showing 5 levels of indented text.
# Results:  Basic panel using indented lines.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.statictext('Normal placement.')
pan.statictext('The letter capital O is for scale.')

pan.statictext('O')
pan.begin_indent(indent=1)
pan.statictext('Indent = 1.')
pan.end_indent()

pan.statictext('OO')
pan.begin_indent(indent=2)
pan.statictext('Indent = 2.')
pan.end_indent()

pan.statictext('OOO')
pan.begin_indent(indent=3)
pan.statictext('Indent = 3.')
pan.end_indent()

pan.statictext('OOOO')
pan.begin_indent(indent=4)
pan.statictext('Indent = 4.')
pan.end_indent()

pan.statictext('OOOOO')
pan.begin_indent(indent=5)
pan.statictext('Indent = 5.')
pan.end_indent()

pan.display()

panel.begin_same_line(self)

panel.end_same_line(self)

Position elements on the same line. All elements between begin_same_line() and end_same_line() will be positioned side-by-side instead of stacked one above the other.

# Filename: gui_begin_same_line.py
# Purpose:  Create a panel showing 4 frame blocks side-by-side.
# Results:  Messagebox showing selected results.

from maptek import vulcan_gui

pan = vulcan_gui.panel(title="Basic Panel")

pan.begin_same_line()


# additional spaces were added to prompt one to increase the width
pan.begin_block(border=True, title='First Block')
pan.radiobutton(tag='rad_1', prompt='One            ', initial=True, bank=0)
pan.radiobutton(tag='rad_2', prompt='Two', initial=False, bank=0)
pan.end_block()

pan.begin_block(border=True, title='Second Block')
pan.radiobutton(tag='rad_3', prompt='One            ', initial=True, bank=1)
pan.radiobutton(tag='rad_4', prompt='Two', initial=False, bank=1)
pan.end_block()

pan.begin_block(border=True, title='Third Block')
pan.radiobutton(tag='rad_5', prompt='One            ', initial=True, bank=2)
pan.radiobutton(tag='rad_6', prompt='Two', initial=False, bank=2)
pan.end_block()

pan.begin_block(border=True, title='Fourth Block')
pan.radiobutton(tag='rad_7', prompt='One            ', initial=True, bank=3)
pan.radiobutton(tag='rad_8', prompt='Two', initial=False, bank=3)
pan.end_block()

pan.end_same_line()

pan.display()

if pan['rad_1']:
    r1 = 'First Block: One'
else:
    r1 = 'First Block: Two'

if pan['rad_3']:
    r2 = 'Second Block: One'
else:
    r2 = 'Second Block: Two'

if pan['rad_5']:
    r3 = 'Third Block: One'
else:
    r3 = 'Third Block: Two'

if pan['rad_7']:
    r4 = 'Fourth Block: One'
else:
    r4 = 'Fourth Block: Two'

message = (r1 + '\n' + r2 + '\n' + r3 + '\n' + r4)
vulcan_gui.message(message)

panel.skip_line(self)

Positions an element below the previous element after skipping a line.

# Filename: gui_skip_line.py
# Purpose:  Create a panel showing 2 fileselectors separated by a space.
# Results:  Messagebox showing selections.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.fileselector('tri', 'Select surface', '*.00t', width=20)
pan.skip_line()
pan.fileselector('grd', 'Select grid', '*.00g', width=20)
pan.display()

# do something with the user's response to the panel.
tr = pan['tri']
gr = pan['grd']
vulcan_gui.message('Triangulation: ' + pan['tri'] + '\nGrid: ' + pan['grd'])

Figure 3: Without using skip_line().

Figure 4: Same panel using skip_line().

panel.statictext(self, prompt, bold=False)

Text placed on the panel.

Parameters

prompt ('string')
bold (bool)

# Filename: gui_statictext.py
# Purpose:  Create a panel showing static text.
# Results:  Basic panel showing static text.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.statictext('Use static text for instructions or labels.', bold=False)
pan.display()

panel.get_values(self)→ MVariant

Gets the values from the panel (after it has run) and saves them to a dictionary.

# Filename: gui_get_values.py
# Purpose: Gets values from a panel (after it has run) and save to dictionary.
# Returns: Dictionary.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='checkbox_1', prompt='Checkbox one', checked=False)
pan.checkbox(tag='checkbox_2', prompt='Checkbox two', checked=False)
pan.checkbox(tag='checkbox_3', prompt='Checkbox three', checked=False)
pan.display()

dict = pan.get_values()
print(dict)

dict = {'checkbox_2': 1, 'checkbox_3': 0, 'checkbox_1': 0}

panel.set_values(self, values)

Preloads panel key values using dictionary.

Parameters

values (dictionary)

# Filename: gui_set_values.py
# Purpose: Preloads panel key values with input dictionary values.
# Returns: Void.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='checkbox_1', prompt='Checkbox one', checked=False)
pan.checkbox(tag='checkbox_2', prompt='Checkbox two', checked=False)
pan.checkbox(tag='checkbox_3', prompt='Checkbox three', checked=False)

pan.set_values({'checkbox_2': 1, 
                'checkbox_3': 0, 
                'checkbox_1': 0
               })

pan.display()

panel.save_spec(self, specName)

Saves the panel data to a specification file. This method call needs to be placed after the display() method call.

Parameters

specName (string) - Name of specification file including extension.

Note: The spec file is saved in the directory from which the script is run.

# Filename: gui_save_spec.py
# Purpose: Saves the panel data to a specification file.
# Returns: Void.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='checkbox_1', prompt='Checkbox one', checked=False)
pan.checkbox(tag='checkbox_2', prompt='Checkbox two', checked=False)
pan.checkbox(tag='checkbox_3', prompt='Checkbox three', checked=False)
pan.display()

pan.save_spec('settings.spec')

panel.load_spec(self, specName)

Loads a specification file into the panel. This method call needs to be placed before the display() method call.

Parameters

specName (std::string const &)

# Filename: gui_load_spec.py
# Purpose: Loads a specification file into the panel.
# Returns: Void.

from maptek import vulcan_gui

pan = vulcan_gui.panel("Basic Panel")
pan.checkbox(tag='checkbox_1', prompt='Checkbox one', checked=False)
pan.checkbox(tag='checkbox_2', prompt='Checkbox two', checked=False)
pan.checkbox(tag='checkbox_3', prompt='Checkbox three', checked=False)

pan.load_spec('settings.spec')
pan.display()