Getting Started With
Gumption
from Seagrape Software
Contents
Introduction
3
Build A Database
4
Run and Design Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
The Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
The Card
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
The Field
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
The Attributes Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
Duplicate Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
The Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
Build The Simplest Application: Hello World
8
The Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
The Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Message Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Variations on a theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Build A Useful Application: A Stopwatch
12
Learning the Python Language . . . . . . . . . . . . . . . . . . . . . . . . 12
The Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Stopwatch Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
The Event Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
The Stopwatch: Adding Features
16
The Event Watcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
The Menu Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
The Run and Design Menus . . . . . . . . . . . . . . . . . . . . . . 17
Kinds of Menu Items
. . . . . . . . . . . . . . . . . . . . . . . . . . 17
Event Handler Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Deleting Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Required Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Top Level Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Sub Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1
Sub Sub Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Stopwatch Menu Scripts . . . . . . . . . . . . . . . . . . . . . . . . 21
Shortcuts
Name
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Revert To Saved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Set To Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Runtime Events
25
Using The Console To Control The Stack
26
Console Shortcuts
27
Dialogs
28
Ask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Get Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Get File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Get Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Get Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Get Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Get Single Choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Get Single Choice Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2
Introduction
Thanks for trying our product. Well, what is it?
Figure 1: A Bare-Bones Stack
Gumption is a powerful and versatile toolkit for building computer applications using
the Python language. With a few mouse clicks you can easily create screens with
buttons, checkboxes, radio buttons, list boxes, combo boxes, and more. The built-in
script editor allows you to write the Python code for your application, and comes
with tools that make Python coding easier:
• A navigator that displays a list of functions, classes, and methods.
• Code folding to collapse or expand blocks of text for easier reading.
• Color themes.
Applications built using Gumption are cross-platform so they can be used on Windows, OS X, and Unix computers with no recompiling. Because Gumption uses
native widgets, your application will look correct for the operating system it’s running on.
3
Build A Database
A database is, simply put, a collection of data that’s organized into records. The
box of recipes in your kitchen is a database. So is the program that stores all of
the financial transactions of a major company. Rather than talk a bunch of theory,
let’s build a simple database that shows off the basics of Gumption. We’ll build an
address book.
Run and Design Modes
Gumption has two modes: Design and Run. In design mode you build the application–
widgets can be added to the screen, dragged around, and resized. In run mode you
execute the application– any scripts assigned to the objects are executed. To select
the mode, choose Go > Run or Go > Design.
The Stack
A Gumption stack is like a stack of index cards. In its simplest form a stack has a
single card and a single group. Create a new stack by choosing File > New Stack.
The Card
A card is a window drawn on the screen. In the address book example, each card
represents one record of the address book, which represents the information of
one person. A database stack can have thousands of cards, while an application
stack that plays music files might have only one card which contains the controls
for playing music. Cards are shown one at a time.
The Field
A field is a container for text. It can hold a single character, or thousands of lines.
Read-only fields can be used for labeling other components, while read-write fields
allow the user to type in and edit text.
Create a field by choosing Objects > New Field. A field is created in the middle of
the card.
Notice that the field is surrounded by eight small blue squares. These are the resize
handles. Click on the lower right resize handle and drag it around while holding
down your mouse button if you’re doing this in OS X (or while holding down your
left mouse button if you’re doing it in Windows or Unix). Notice that the field is
resized. To move the field, click and drag on the field itself.
4
Figure 2: Field with Resize Handles
The resize handles at the corners can be moved either up/down or left/right. The
other four resize handles can be moved only in one direction: the handles at the top
and bottom edges can be moved only up/down. The handles at the left and right
edges can be moved only left/right. They allow you to resize the field in only one
direction without worrying about changing the other direction.
The Attributes Browser
Python is an object-oriented language, which requires a bit of explanation. The
aforementioned stack, cards, and fields are objects. So are ladybugs, hurricanes,
and sports cars. A ladybug has attributes that describe her: she has a position in
space, a size, and a color. Gumption objects also have attributes: a stack has a
title, and a field has a label that contains the text it displays. One way to change
a Gumption object’s attributes is to use the Attributes Browser, which is available
only in design mode. To show the Attributes Browser, choose Objects > Stack Attributes. . .
Click in the Title field on the Attributes Browser and type Hello World. The stack
title is updated as you type. Now click in the card area of the stack, which is below
the title bar.
The Attributes Browser is now loaded with the attributes of the card. Click on the
field. The Attributes Browser is loaded with the field attributes, and the resize handles are drawn around the field.
Duplicate Card
Let’s continue building the address book. Click on the field created earlier and drag
it to the upper left corner of the card. Set it to read-only: return to the Attributes
5
Figure 3: The Attributes Browser
Browser and click on the Advanced tab, and then click on the Read Only checkbox.
Click on the General tab, and set the field label to First Name. Follow the design
shown in Figure 4 and create the rest of the fields, using a read-only field paired to
a read-write field. Clear the read-write field’s label of any default text. (The user will
be entering text at run time.) To help make the controls a uniform size and position
use the Snap To Grid option. To activate it, choose Edit > Snap To Grid.
Figure 4: The Address Book
Now the card is covered with an invisible grid, and when you when you reposition
and resize a control it snaps to the nearest grid point. Try it by dragging a field
6
around. Once you get your controls semi-uniform and looking good, it’s time to go
into run mode. Choose Go > Run.
Click on one of the read-write fields, and type in some text. You’ve created a single
record (card) of a database (stack). Create another record by duplicating the card.
Choose Objects > Duplicate Card-Group. A duplicate card is created and shown
and the read-write fields are blank, but the read-only fields are still filled in with text.
Now fill in the read-write fields of the card. How to flip back to the original card?
Choose Go > Next Card-Group or Go > Previous Card-Group. Now you can create
databases of, well, anything you can think of.
The Group
We can now create new records for the address book easy enough, but what if
we want to redesign it after accumulating several records? Put the stack back into
design mode: choose Go > Design.
Click on the read-only field labeled First Name and move it with the mouse. Easy
enough. Now go to another card. Its field is still in the original position. So if you
design a database with a thousand cards and want to rearrange the card design,
you will have to make the change to each card of your database, one at a time.
There is an easier way, by using a common group for the cards. Groups are a way
of sharing controls between cards. Sharing will save you from duplication of effort,
which is the bane of programmers everywhere. Never do the same task or solve the
same problem more than once, unless you really want to. Once you have the fields
assigned to a single group that all cards use, then changing a group field once will
percolate the changes to every card that uses the group.
We’ll move the controls to a single shared group, but first, leave only one card on
the stack. Delete the card that was created previously by clicking on the card to
ensure that no resize handles are shown, then choose Edit > Delete. Next, select
all the fields on the remaining card, which can be done two different ways: either
choose Edit > Select All or click and drag the mouse across all of the fields at once.
Don’t worry if you make a mistake, Edit > Undo will undo any changes you make.
Choose Edit > Cut to remove the fields. The card is now blank.
Choose Go > View Groups. You are now in Group mode which allows you to flip
through all your groups as if they were cards. Choose Edit > Paste to paste the
fields on the group.
Next, tell the card to use the group: choose Go > View Cards to display the card,
then on the Attributes Browser, click on the Advanced tab. Click on the checkbox
for Group 0 in the Assigned Groups list. Duplicate the card with Objects > Duplicate
Card-Group. The duplicate card uses the same group as the original. Now when
you rearrange the group fields, the changes are shown on each card that uses the
group.
A stack can have thousands of groups and cards. In fact a card can be assigned
thousands of groups, though it would be unusual to have that many.
7
Build The Simplest Application: Hello World
The previous database required no Python code at all, so next we’ll build a singlecard application that has a script. Keeping with a long-standing tradition in the computer world, this script will, when a button is clicked, pop up a message box that
says Hello World. Create a new stack: choose File > New Stack.
The Button
A button is an object that says to the user “Push me. Make something happen”, so
the application will use a button to make the message box appear. Create a new
button: choose Objects > New Button.
The Script Editor
The application needs some Python code to make the button do something when
we click it. Gumption has a built-in text editor for writing Python scripts. To open the
Editor, choose Edit > Script Editor. The editor has a number of features that can be
configured by choosing Options > Preferences from its menu.
Figure 5: The Script Editor
Code Folding You can show or hide sections of code by clicking on the [+] or [-]
icons in the editor’s margin.
Indent Guides The Python language uses indentation for denoting blocks of code.
Because your scripts won’t work correctly unless the indentation is correct,
the script editor can provide vertical guides to show the current indentation
level as set by the tab width.
8
Figure 6: A script with the bottom function folded
Figure 7: The editor with indent guides shown
Navigator The navigator is a menu item containing a list of classes, functions, and
methods for the current script. When you click on an item in the menu, the
cursor is moved to the appropriate place in the code.
Themes The editor allows you to color code text to make it more readable. For
instance setting all comments to a distinct color makes it easier to pick out
the comments for reading.
Create a short script by typing the following into the editor:
def o n _ c l i c k ( ) :
p r i n t ( ’ H e l l o World ’ )
9
Figure 8: Editor Themes
Scripts
A script is a string of text that tells an object to do something. Scripts in Gumption
are written in the Python language. You can write a script to do something when
the stack is opened, or when a card is clicked on, or when you run the mouse over
a button. Scripts which are executed when an event takes place (like clicking on
a button, or closing a stack) are called, appropriately enough, event handlers. You
can write scripts that have only one event handler or thousands. You could write a
script that has no event handlers, but it would be a pretty boring stack and would
sit there and do nothing.
If you are familiar with the Python language you will probably notice the previous
script contains a function definition. The function on_click() is an event handler
called when you mouse click on a button. For a complete list of Gumption events,
see Runtime Events.
Save the script: choose File > Save. Close the editor: choose File > Exit Editor.
Run the stack: choose Go > Run. Click on the button. A message box pops up and
displays Hello World.
The Message Box
Whenever a script says print(‘hello’), hello will be printed in a message box that
pops up. The message box displays the result of any print statements, and any
error messages if your scripts have a bug.
10
Figure 9: The Message Box
Variations on a theme
Now to use another form of output display. Rather than using the standard message
box, let’s use something a bit more interesting. Close the message box. Choose Go
> Design. Click on the button to select it, and edit the script: choose Edit > Show
Editor. Change the script to the following:
def o n _ c l i c k ( ) :
answer ( ’ H e l l o w o r l d ! ’ )
Save and close the script: choose File > Save, then File > Exit Editor. Run the
stack: choose Go > Run. Click on the button. Rather than using the message box
to display text, you used a custom dialog box called answer(). Dialogs are used
for giving or asking for information in a way that grabs the user’s attention. For a
complete list, see Dialogs.
11
Build A Useful Application: A Stopwatch
Next, we will build an application that uses more controls– fields, a timer, and a
more complex script. Let’s build a stopwatch.
You already know how to create a new stack, buttons, and fields, so create a new
stack with three buttons and one field. Using the Attributes Browser, set the names
and labels of the buttons to Start, Stop, and Reset respectively. Set the label of the
field to 00:00 and set the field to read-only. Set the name of the field to Display.
Giving an object a name allows the stack to easily find it amongst all the other
objects it contains. Use a larger font on the field if you like, to make it look like a
nice, big stopwatch display.
Figure 10: The Stopwatch
Learning the Python Language
While you can build databases and such in Gumption without writing a single line of
code, in order to get the most out of Gumption you will need to jump in and learn the
Python programming language. The official Python documentation has an excellent
tutorial here, which will give you a good overview of the language.
If you decide to work through the Python tutorial, please note that you can type in
your Python commands by using the built-in console discussed below.
The Console
Gumption allows you execute Python code in one of two ways: you can use the
editor to write Python scripts which are later executed in Run mode, or you can
type the commands into the console window and have them execute immediately.
To open the console, choose Edit > Console. . . You will see a window with a command prompt > > >. After the command prompt, type 3 + 4 and hit Enter. A 7 is
printed. Because the console has a built-in Python interpreter, you can use it to
12
work through the Python tutorial. The console can also control the stack directly:
see Using The Console To Control The Stack.
Stopwatch Scripts
Next, create the following scripts for their respective objects. You will notice a class
called Timer(). It’s the software equivalent of an egg timer, sitting in the shadows
and quietly ticking away. The stopwatch will need a timer.
Stack Script
def on_open_stack ( ) :
global tmr , t o t a l _ s e c o n d s
tmr = Timer ( )
total_seconds = 0
def o n _ t i m e r ( ) :
global t o t a l _ s e c o n d s
t o t a l _ s e c o n d s += 1
update_display ( total_seconds )
def u p d a t e _ d i s p l a y ( sec ) :
f i e l d = s t a c k . find_object_by_name ( ’ D i s p l a y ’ )
seconds = sec % 60
minutes = sec / 60
elapsed = ’ %0.2d : %0.2d ’ %(minutes , seconds )
f i e l d . s e t _ l a b e l ( elapsed )
Start Button Script
def o n _ c l i c k ( ) :
global tmr , t o t a l _ s e c o n d s
tmr . s t a r t ( 1 0 0 0 )
update_display ( total_seconds )
Stop Button Script
def o n _ c l i c k ( ) :
global tmr
tmr . s t o p ( )
Reset Button Script
def o n _ c l i c k ( ) :
global t o t a l _ s e c o n d s
total_seconds = 0
update_display ( total_seconds )
13
The Event Hierarchy
Notice in the previous section, the update_display() function is part of the
stack script, and the button scripts make a call to this function. How do the button
scripts know where to find it? There is a search order in Gumption, and functions
and classes are first searched for in the script they are referred to. In this case,
it’s the button script. The function isn’t found there, so the button’s card script is
searched, then any groups the card uses, then finally the stack script. This is designed to save you work. If you have a function or class that is used by several
objects on the same card, just put the code in the card script. If you have some
code that will be used by several cards that use the same group, put the code in
the group script. And if you want every object in the stack to be able to access the
code, put the code in the stack script.
Stack
Group
Card
Button,
Field, or Pic
Figure 11: The Event Hierarchy
As shown in The Event Hierarchy, the event search path is one way, from bottom to
top. An object can call a function only from objects above it in the event hierarchy,
not below it. This means that a button or field script can call a function in either
the card, group, or stack script. A card script can call a function in either the group
or stack script. And so on. The stack script cannot call functions from other object
scripts.
14
What if there is a function in the stack script that has the same name as a function
in a button script? Then the button script’s function will be used. The function in the
script that is lower in the event hierarchy overrides the function in the script of the
higher.
15
The Stopwatch: Adding Features
Next, we’ll add some new capabilities to the stopwatch we built previously, and in
the process learn about some advanced features built into Gumption.
The Event Watcher
So far, our stopwatch application has events that take place when you click a button,
when you select a menu, and when the timer rolls over. What if you want to observe
these events taking place? One way is to put a print statement in your button’s
on_click() event handler. Another way that does not require you to modify any
scripts is to use the Event Watcher. Choose Edit > Event Watcher. . .
Figure 12: The Event Watcher
Clear the checkbox labeled “Hide Unused”. Put the stopwatch stack into Run mode
and click on the stack, move it around, resize it; generate lots of events. As you
can see, all events are displayed in the Event Watcher, even events that don’t have
handlers written for them. Click the checkbox labeled “Hide Unused”. Now only
the events that have handler scripts are shown, and the only event handler scripts
we’ve written are for the Timer and the Start, Stop, and Reset buttons.
The Menu Builder
When the stopwatch is in Run mode, the application has a lot of menu items that
aren’t really applicable. After all, you’re not going to add or delete cards; you just
need menu items to start, stop, and reset the stopwatch. To build a custom runtime
menu, we use the Menu Builder. To open the Menu Builder, choose Edit > Menu
Builder. . .
16
Figure 13: The Menu Builder
The Run and Design Menus
The Menu Builder shows the menu items displayed when the stack is in Run mode.
The menu displayed in Design mode is fixed and cannot be changed, so the Menu
Builder affects only the Run menu.
Kinds of Menu Items
There are three kinds of menu items: a plain vanilla item, a check item, and a
separator. A menu is composed of one or more top-level menu items, each of which
has its own submenu. For instance, the top-level Gumption menu item “File” has a
submenu composed of items “New Stack”, “Open Stack”, “Save Stack”, etc.
Items that aren’t top-level can have a script that handles events. In fact they should
have an event handler script or they will sit and do nothing when clicked by the user.
17
Figure 14: The File Menu
The check item is shown in Figure 15, and is an item with a checkbox. The check
item can also have a script to handle events.
Figure 15: A Check Menu Item
Finally we have the menu separator. It is simply a horizontal bar used for breaking
18
up a large menu list into smaller sections. Grouping together related items in this
way will make your menus easier to read. Separators cannot have a script.
Event Handler Scripts
On the Menu Builder, click on the Print. . . command of the File menu in order to
highlight it and then click the “Edit Script” button. You will see the event handler
script for the “Print. . . ” item.
def o n _ c l i c k ( ) :
menu . p r i n t _ o b j e c t s ( )
This script tells Gumption to execute the menu system’s print_objects() method.
Using the Editor, change the event handler to the following:
A Menu Script To Say ‘Hello’
def o n _ c l i c k ( ) :
answer ( ’ h e l l o ! ’ )
Choose File > Save Menu, then Go > Run. Now activate your new menu event
handler by choosing File > Print. . . An answer box should pop up.
Deleting Menu Items
We’re going to modify the runtime menu to be more suitable for our stopwatch
application. Choose Go > Design. Get rid of all the default menu items by choosing
Edit > Select All, then Edit > Delete, then File > Save. All the menu items are
removed. But are they?
Required Menu Items
Put the stack in Run mode. Even though you already deleted all the menu items
previously, you still have a menu composed of only a few items. One menu item is
the Design command of the Go menu. It’s inserted automatically in stacks opened
using the Gumption development environment. After all, without it how can you get
back into design mode? The other menu item automatically created is the Help >
About Gumption menu. This menu item is included because it contains the Gumption copyright information, and for cross-platform compatibility. The Apple OS X
operating system requires a Help menu item, and if we didn’t provide one, the operating system would insert one. So Gumption beats OS X to the punch and inserts
the Help item on all three platforms (Windows, Unix, Apple OS X)
19
Top Level Menu Items
Top level items are flush with the left edge of the Menu Builder list control. Create a
top level item called “Choose”: click “Add” then type “Choose” in the Label text box.
Sub Menu Items
Create another item called “Start”: click “Add” then type “Start” in the Label text
box. To change an item from top-level into a submenu item, ensure the item is
highlighted and click the right arrow once to indent it. Your menu should resemble
Figure 16.
Figure 16: Choose -> Start
Add two more sub menu items: “Stop” and “Reset”, indenting them like the “Start”
item. Choose File > Save, then Go > Run. Notice that “Start”, “Stop”, and “Reset”
are part of the submenu of the “Choose” top-level item.
20
Figure 17: The Complete Stopwatch Menu Design
Sub Sub Menu Items
Sub menu items can have their own sub sub menus. Choose Go > Design. Select
the “Reset” item, and click the right arrow once to indent it again. Your menu should
resemble Figure 18
“Reset” is now a submenu of “Start” and a sub submenu of “Choose”. Note: the
only items that can trigger a menu event and have their scripts execute are the last
links of the menu chain. Top-level items won’t trigger a menu event, and if a sub
menu item has its own sub sub menu, like “Start”, it won’t trigger a menu event
either. It won’t cause an error if it has an event handler script, the script just won’t
execute. In our example, only the “Stop” and “Reset” menu items will trigger a menu
event. Choose Go > Design and convert the “Reset” item back into a sub item of
“Choose”: in the Menu Builder select “Reset” item and click the left arrow once to
dedent (unindent) it.
Stopwatch Menu Scripts
The submenu items “Start”, “Stop”, and “Reset” need event handler scripts in order
for them to do something useful. Create the following functions in their respective
button scripts after you delete the old button script code.
21
Figure 18: Menu Builder Choose, Start, Stop, and Reset
Start Button Script
def o n _ c l i c k ( ) :
start ()
Stop Button Script
def o n _ c l i c k ( ) :
stop ( )
Reset Button Script
def o n _ c l i c k ( ) :
reset ( )
Next we need to modify the stack script we wrote previously in order to allow the
menu event handler use the start(), stop(), and reset() functions. We’re
22
just consolidating the scripts of the “Start”, “Stop”, and “Reset” buttons into functions stored in the stack script.
Stack Script
def on_open_stack ( ) :
global tmr , t o t a l _ s e c o n d s
tmr = Timer ( )
total_seconds = 0
def o n _ t i m e r ( i d ) :
global t o t a l _ s e c o n d s
t o t a l _ s e c o n d s += 1
u p d a t e _ d i s p l a y ( t o t a l _ s e c o n d s / 10)
def u p d a t e _ d i s p l a y ( sec ) :
f i e l d = s t a c k . find_object_by_name ( ’ l b l _ t i m e ’ )
seconds = sec % 60
minutes = sec / 60
elapsed = ’ %0.2d : %0.2d ’ %(minutes , seconds )
f i e l d . s e t _ l a b e l ( elapsed )
def s t a r t ( ) :
global tmr , t o t a l _ s e c o n d s
tmr . s t a r t ( 1 0 0 )
update_display ( total_seconds )
def s t o p ( ) :
global tmr
tmr . s t o p ( )
def r e s e t ( ) :
global t o t a l _ s e c o n d s
total_seconds = 0
update_display ( total_seconds )
Shortcuts
We’ve finished the stopwatch menu, so let’s go over some of the features in the
Menu Builder that weren’t covered previously.
Keyboard menu shortcuts allow you to use the keyboard instead of the mouse for
triggering menu events. For instance, pressing the Control-S key combination is the
universal keyboard shortcut to save a project or document. Keyboard shortcuts are
universal, so users will be unhappy if your application doesn’t have them.
23
There are two kinds of menu shortcuts: the mnemonic shortcut and the accelerator
shortcut.
A mnemonic shortcut is an underlined letter of a menu label that, when combined
with the Alt key, causes the menu to unfold. For example, in many applications, AltF will display the File menu. When using the Menu Builder, putting the & character
before a letter in the menu label will make that letter the mnemonic shortcut. The
label &File will have F as the mnemonic shortcut. Apple OS X does not recognize
mnemonic shortcuts. You can still add them to your menus and it won’t cause a
program crash in OS X. It just won’t use them.
An accelerator shortcut, unlike a mnemonic, doesn’t actually cause the menu to
unfold and be displayed; it simply executes the event handler.
A mnemonic shortcut uses the & in the label. An accelerator has three or more
components:
1. The Alt, Ctrl, or Shift key, or any combination of the three.
2. The key of the accelerator. This can be any alphanumeric key, F1 through
F12, or one of the special keys listed in the Menu Accelerator Shortcuts.
Note that some keys have more than one accelerator that can be used. For
instance, the Delete key can use the accelerators Del or Delete.
3. A separator - or + to separate each of the components listed above.
Here are three examples of accelerators:
• Alt+R
• Ctrl-F1
• Alt+Shift+9
Name
A name can be assigned to the menu object. This can make it easier for scripts
to find the item during run time by using the stack.find_object_by_name()
method.
Revert To Saved
To revert back to the previously-saved menu, choose File > Revert To Saved.
Set To Default
The default runtime menu is a carbon copy of the design time menu. To set the
runtime menu back to the design menu, choose File > Set To Default.
24
Key Name
Accelerator(s)
Delete
Down Arrow
End
Enter
Escape
Home
Insert
Left Arrow
Page Down
Page Up
Enter
Right Arrow
Space Bar
Tab
Up Arrow
Del, Delete
Down
End
Enter
Esc, Escape
Home
Ins, Insert
Left
Pgdn
Pgup
Return
Right
Space
Tab
Up
Table 1: Menu Accelerator Shortcuts
Runtime Events
Event Name
on_click()
on_text_enter()
on_text_update()
on_left_down()
on_left_double_click()
on_middle_down()
on_middle_double_click()
on_right_down()
on_right_double_click()
on_enter_object()
on_leave_object()
on_mouse_wheel()
on_motion()
on_timer()
on_idle()
on_open_card()
on_close_card()
on_open_group()
on_close_group()
on_open_stack()
on_close_stack()
on_move()
on_resize()
Event Trigger
Mouse clicked
Enter key pressed when the cursor is in a read-write field
Text changed when the cursor is in a read-write field
Left mouse button pressed down
Left mouse double clicked
Middle mouse button pressed down
Middle mouse button double clicked
Right mouse button pressed down
Right mouse button double clicked
Cursor enters the object
Cursor leaves the object
Mouse wheel spun
Cursor moved around on the object
Timer event
Nothing happening (no mouse clicks or cursor movements)
Card shown
Card not shown (going to a different card)
Group shown
Group not shown
Stack opened
Stack closed
Stack moving
Stack resized
25
Using The Console To Control The Stack
The console can talk directly to the stack. Create a new stack: choose File >
New Stack. Create a button on the card: choose Objects > New Button. After
the command prompt, type stack.set_title(’This is the new stack
title’) and hit Enter. The console can also talk to every other object in the stack.
After the command prompt, type card = stack.cards[0] and hit Enter. The
name card has been assigned to the first card in the stack.
Next type button = card.buttons[0] and hit Enter. The name button has
been assigned to the first (and only) button on the card. Type button.move(20,
30) and hit Enter. The button is moved to the coordinates, x = 20 and y = 30. Using
the stack API you can control the stack from the console just as you can control it
using scripts. To show the stack API, choose Help > Gumption Help.
26
Console Shortcuts
Key(s)
Home
End
Shift + Home
Shift + End
Ctrl + C
Ctrl + Shift + C
Ctrl + X
Ctrl + V
Ctrl + Shift + V
Ctrl + Up Arrow
Alt + P
Ctrl + Down Arrow
Alt + N
Shift + Up Arrow
Shift + Down Arrow
Ctrl + Enter
Ctrl + ]
Ctrl + [
Ctrl + =
Ctrl + Space
Ctrl + Alt + Space
Shift + Enter
Ctrl + F
F3
F12
Action
Move cursor to the start of the line
Move cursor to the end of the line
Select all text to the start of the line
Select all text to the end of the line
Copy selected text, removing prompts
Copy selected text, retaining prompts
Cut selected text
Paste text from clipboard
Paste and run multiple commands from clipboard
Retrieve previous history item
Retrieve previous history item
Retrieve next history item
Retrieve next history item
Insert previous history item
Insert next history item
Insert new line into multiline command
Increase font size
Decrease font size
Default font size
Show Auto Completion
Show Call Tip
Complete Text from History
Search
Search next
Toggle on/off Free-edit mode: commands aren’t executed
27
Dialogs
A dialog is a separate window that pops up to communicate with the user. A dialog
can be a simple one that displays some text for the user to read, or it can ask the
user to select an item from a list, or it can ask the user to type in some text. Because
the user has to click a button or press a key to make the dialog disappear, dialogs
are great for communicating to the user in a way that is very intrusive. Use them
sparingly.
For a non-intrusive way to communicate with the user a good option is to use the
status bar, which is discussed in the Help files.
Ask
Ask the user to enter some text.
Figure 19: Ask Dialog
Answer
Display some text for the user to read.
Figure 20: Answer Dialog
28
Get Directory
Display a directory selector.
Figure 21: Get Directory Dialog
29
Get File
Display a file selector.
Figure 22: Get File Dialog
30
Get Color
Display a color selector.
Figure 23: Get Color Dialog
Get Number
Display a dialog that requests the user to type in a number.
Figure 24: Get Number Dialog
31
Get Password
Display a dialog that requests the user to type in a password.
Figure 25: Get Password Dialog
Get Single Choice
Display a dialog that requests the user to select an item from a list. Returns the text
label of the item selected.
Figure 26: Get Single Choice Dialog
32
Get Single Choice Index
Display a dialog that requests the user to select an item from a list. Returns the list
index number of the item selected.
Figure 27: Get Single Choice Index
c 2014 Seagrape Software, LLC
Copyright 33