To modify any built-in property of a component in the resourceEditor,
you first select the object, which you can do either by clicking on the
component in the Resource Editor Window or by selecting it from the list
of objects in the Property Editor Window. Then you select the property you
wish to change from the scrolling list of properties, make the appropriate
adjustment to the setting, and click the "Update" button to instruct the
resourceEditor to apply the new setting.
Each component has a set of properties, some of which are shared with
all or some other components and some of which may be unique to the specific
component. These properties are delineated in the soon-to-be-published PythonCard
Component Description document.
The Size & Position Window displays those parameters for the selected
window in your application or for the selected component in the window,
but its contents are not editable. To change those properties, you must
either directly manipulate the component or edit the appropriate property.
Managing Background Properties
Every window in a PythonCard application automatically includes a background.
This background describes the characteristics of the window as a whole, and
acts as the backdrop against which components are placed and which is the
container of those components.
As we saw in Figure 4, above, you can modify the properties of the application
windows' backgrounds using the Background Information Editor, which is
displayed by selecting "Background Info..." from the resourceEditor's "Edit"
menu.
You will want to change the background's name to something that reflects
your application's name if for no other reason than it will be easier to
remember its name when you refer to it in your Python scripts. The Title
field should contain the text you want to display as the window's title in
its title bar.
The position and size settings are the default values. When the window
opens, it will open at that location on the screen and at the indicated
size. You'll find that if you resize the window and move it around on the
screen, then reopen the Background Information Editor, it will update to
reflect your changes.
(
Note that in the current release of PythonCard, it is not possible
to make a fixed-size window that the user cannot resize. When the user
does resize a window, then exits the application, the windows will
restore themselves to their default sizes and positions on restart unless
you specifically write Python code to override those settings.)
You can alter the foreground and background colors of the window using
standard color selector dialogs for your system. In this release, we recommend
you not alter those properties if you intend to run your PythonCard application
on other platforms because cross-platform color compatibility is still
a bit shaky in wxPython. It is possible to give your window a graphic image
as a background. If you check the "Tile" checkbox, the image will appear
in its original size, tiled as needed to fill the background. If you do not
check "Tile," the image will be stretched or collapsed to the size of the
window.
If you wish to select an icon to represent your application when it is
collapsed or in the launch area for the system on which it runs, identify
the image file for the icon in the space provided. If you do not supply
an icon, PythonCard uses the standard Python icon, a cute green snake.
The last two items you can control about a background are whether it
displays a status bar (default is off) and whether it is visible when your
application starts (default is on).
Once you make changes to the background, you should save your application's
resource file.
Managing Menus
The PythonCard resourceEditor incorporates a full-featured menu editor
that uses industry-standard terminology and allows you to define shortcuts
and accelerator keys for all menu options. Figure 12 shows you what the
Menu Editor looks like when it has a complex set of menus defined. (It actually
depicts the menus in the resourceEditor itself.)
Figure 12. Menu Editor Showing Menus in resourceEditor's Resource File
You can add a new menu by clicking on the New Menu button.
The result looks like Figure 13. Notice that the new menu is called "New
Menu" and appears at the bottom of the current list of menus in the application.
Figure 13. Menu Editor Showing New Menu Being Defined
By convention, you should name your menus starting with
the word "menu" (in lower case), followed by the name of the menu itself
(e.g., the File menu). The File menu should be named menuFile. Following
this convention makes it easy to remember their names when you are writing
the Python scripts to respond to the user's selection of your menus.
Similarly, you create new items to appear on menus by clicking the "New
MenuItem" button in the Menu Editor. This creates a new menu item at the
bottom of the current list of menus and menu items, as shown in Figure 14.
Figure 14. Menu Editor Showing New Menu Item Being Edited
Again, naming conventions are useful. We recommend you
name new menu items beginning with the tag "menu", followed by the name of
the menu on which the item appears (e.g., File), and then by the name of
the item itself (e.g. Exit): menuFileExit.
In providing a label for a menu item (but not, of course, for a menu,
which is not executable), you may select an accelerator key by preceding
any letter in the label with an ampersand ("&"). Figure 15 shows an example
of this using the menuFileOpen menu item. Notice the ampersand preceding
the letter "O" in the menu item's label. This means the user can select the
File Open option by typing Alt-F (to select the File menu) followed by Alt-O.
Notice, too, that the Ctrl+O shortcut is also defined, allowing the user
to open a resource file by typing Control-O. To enter a shortcut key combination,
just press the keys you wish to use. PythonCard places a text represetation
of the key combination in the field.
Figure 15. Menu Editor Showing Menu Item With Accelerator Key and Shortcut
Defined
You can also connect the menu to a command object defined
in your Python script (see "Connecting Components and Menus to Scripts,"
below). In addition, you can determine whether the menu item is enabled
when the application launches, whether it is checkable and whether its default
condition is to be checked if it is checkable. PythonCard handles the checking
and un-checking of menu items that are defined as "Checkable" as the user
interacts with the application.
The final feature of the Menu Editor to note is the "Up" and "Down" buttons.
Since new menus and menu items are always created at the bottom of the
list of menus and menu items, we need some way to move them around to associate
them with the appropriate menu and to arrange menus in the desired order.
Selecting any menu or menu item and then clicking the "Up" and "Down" buttons
moves the selected object in the list.
Note that if you wish to create a menu separator within a menu, simply
create a new menu item and make its label a single hyphen. Leave all other
characteristics of the menu item unchanged.
Creating and Editing Dialogs
You can also use the PythonCard resourceEditor to create dialogs to be
used in your application. You create a new dialog by selecting the "New
Dialog" option from the File menu. The resulting editor looks like Figure
16.
Figure 16. Editing Window for New Dialog
Notice that a new dialog template includes two buttons
by default, one labeled "OK" and set as the default button, the other labeled
"Cancel." Editing a dialog is similar to editing a window, with the following
exceptions:
- Dialogs have no menus, so there is no menu editor.
- Dialogs have no backgrounds, so there is no background editor. (There
is instead a Dialog Info... Window, shown in Figure 17, which presents
a subset of a Background Editor containing only information pertinent to
dialogs).
Figure 17. Dialog Information Editor Window
A discussion of how to incorporate dialogs into your PythonCard
applications is beyond the scope of this document. See soon-to-be-published
walkthrough3.html in the PythonCard docs directory of your PythonCard distribution
for a tutorial and example.
Connecting Components and Menus to Scripts
There are two ways to create a connection between an active component
or menu item in your PythonCard application and the application's behavior
as defined in your Python script file: events and commands. Since this
document describes the resourceEditor and since scripting is conducted
outside the resourceEditor, we will here consider only summarily the
process by which these connections are made. For details and examples,
see the tutorial walk-throughs, particularly the soon-to-be-published walkthrough3
and walkthrough4.
Events
When the user activates a component in your PythonCard application, that
action triggers an event. Your Python script consists principally of methods
defining how to respond to user-triggered events. There is a one-to-one correspondence
between the event that is triggered and the name of the method or handler
your program calls in response to the action.
For example, when the user clicks on a button, PythonCard generates a
mouseClick event on that button. The full name of the event passed to your
Python script in the case of a button-press looks like this: buttonSave_mouseClick
(assuming the user has clicked on a button whose name is "buttonSave".)
Note that it is the button's
name, not its
label that
is used here. In your Python script, the handler that will be run when the
user clicks on the Save button would begin with the following line of Python
code:
on_buttonSave_mouseClick(self, event):
Your Python code would then go on to define what you wanted the application
to do when the user clicks on the Save button. If there is no handler called
on_buttonSave_mouseClick, then if the user clicks on the button named buttonSave,
nothing will happen.
Similarly, if the user selects a menu item, the event triggered is called
something like menuFileSave_selected and your handler for this event would
start with a line of Python code like this:
on_menuFileSave_selected(self, event):