API Reference

This module contains the core classes and functions used by PyperCard to create a GUI stack of cards that transition to each other via button presses.

Copyright (c) 2019 Nicholas Tollervey.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class pypercard.core.Card(title, text=None, text_color=None, text_size=48, form=None, options=None, sound=None, sound_repeat=False, background=None, buttons=None, auto_advance=0, auto_target=None)[source]

Represents a “card” in the application. This is a node in a series of possible UI states. Transitions between states are generally facilitated by button presses with either an associated string containing the title of the target card, or a function (containing “business logic”) which returns a string identifying the next card.

Each node has pre-defined attributes which describe the appearance of the card and the behaviour for transitioning to other cards in the application. These are set and verified upon initialisation.

Parameters:
  • title (str) – The unique meaningful title/id of the card.
  • text (str) – The textual content of the card.
  • text_color (str) – The colour of the textual content of the card.
  • text_size (int) – The font size of the textual content of the card.
  • form (Inputs) – The form input element to display on the card.
  • options (tuple) – The form input element’s multiple options.
  • sound (str) – The path to the sound file to play with the card.
  • sound_repeat (bool) – A flag to indicate if the card’s sound loops.
  • background (str) – Either a colour or path to background image.
  • buttons (list) – A list containing button definitions as dictionaries containing label and transition attributes with optional text_size, text_color and background_color attributes.
  • auto_advance (float) – The number of seconds to wait before advancing to the auto_target card.
  • auto_target – Either a string or function returning a string referencing the target card for auto-advancement.
Raises:

ValueError – If the states passed in are inconsistent.

form_value()[source]

Return the value obtained from the user via the form associated with this card. Return None if no form is specified.

Returns:The value currently set for this card’s form.
screen(screen_manager, data_store)[source]

Return a screen instance containing all the necessary UI items that have been associated with the expected event handlers.

Parameters:
  • screen_manager (kivy.uix.screenmanager.ScreenManager) – The UI stack of screens which controls which card is to be displayed.
  • data_store (dict) – A dictionary containing application state.
Returns:

A graphical representation of the card.

class pypercard.core.CardApp(name='A PyperCard Application :-)', data_store=None, stack=None)[source]

An app with more than a passing resemblance to HyperCard stacks. :-)

Parameters:
  • name (str) – The name of the application.
  • data_store (dict) – The dictionary to use as the data store.
  • stack (list) – A list of Card instances defining the default stack.
add_card(card)[source]

Given a card instance, add it to the application.

Parameters:card (Card) – The card instance to add to the application’s stack.
Raises:ValueError – if the card’s title attribute isn’t unique.
build()[source]

Called by Kivy to display something (in this case the screen manager containing all the screens associated with each card).

Returns:The screen manager object containing the stack of cards.
load(filename)[source]

Load and instantiate a stack of cards from the referenced JSON file.

Parameters:filename (str) – The path to the JSON file to load as the application’s stack.
class pypercard.core.Inputs[source]

Defines the available types of form control. Only one form control can appear in each card.

MULTICHOICE = 3

A multi-choice selection.

SELECT = 4

A single choice selection.

SLIDER = 5

A slider with a numeric min, max and step.

TEXTAREA = 2

A multi-line text area.

TEXTBOX = 1

A single line text box.

pypercard.core.palette(name)[source]

Given a name of a colour (e.g. “red”, “green”, “blue”), a hex value (e.g. “0xFFAACC”) or an HTML hex value (e.g. “#FFAACC”), returns a tuple containing the colours converted to Kivy’s own colour coding system.

For a list of all the available colours see the keys in the colours.py module.

Parameters:name (str) – The name of the colour whose value is needed.
Returns:The colour expressed as a tuple of numbers used by Kivy.
Raises:ValueError – if the name of the colour is unknown.