game2dboard 0.8

Python GUI library for creating 2D arrays based board games

game2dboard

A quick and easy way to create board games using 2d arrays in Python. This Python GUI package provides a graphical user interface (GUI) for 2d arrays (matrix).

• What is the aim of this library?
  The aim of the game2dboard is to offer an easy and fun way for students who are new to programming to learn and code programs using arrays.

• What types of games can be created?
  Any that can be modeled on a two-dimensional array, such as checkers, life, tic-tac-toe, chess, 2048, minefield, among many others.

Installation

You can use the pip to install game2dboard:

pip3 install game2dboard

Or install the latest release by cloning the repository:

git clone https://github.com/mjbrusso/game2dboard.git 
cd game2dboard
python3 setup.py install --user

Usage

The API is documented bellow and within the docstrings.

This simple code only provides an overview. See the examples for more details.

Before running, copy this and this files into a img/ folder (credits).

from game2dboard import Board


def mouse_fn(btn, row, col):    # mouse calback function
    b[row][col] = 1 if not b[row][col] else 0

b = Board(3, 4)         # 3 rows, 4 columns, filled w/ None
b[0][0] = 1
b.title = "Click me!"
b.cell_size = 120       
b.cell_color = "bisque"
b.on_mouse_click = mouse_fn
b.show()

Result

Galery

Some screenshots from examples.

Memory Game 58 SLOC View source	Snake 86 SLOC View source

API

Creation

• game2dboard.Board(nrows, ncols)
  Creates a Board.
  • nrows : int – The number of rows.
  • ncols : int – The number of columns.

Indexer

• self[i][j]
  Gets/sets the value at row i, column j.

  When assigning a value, the GUI will be updated. If there is an .png file in the img/ folder whose name is the same as the new value, it will be drawn in position [i][j] of the board. Otherwise, the value will be displayed as text.

  Example:

    b[1][0] = 100            # draw 'img/100.png' @ row 1, column 0
    b[0][2] = "correct"      # draw 'img/correct.png'
    b[3][0] = "wait.png"     # draw 'img/wait.png'
  

Properties

Use properties as class attributes or public fields.
Example:

  b.title = "Hello"       # Sets the window title
  mc = b.margin_color     # Gets the board margin_color

Board properties

• size : int (readonly)
  Number of elements in the array

• nrows : int (readonly)
  Number of rows in the array.

• ncols : int (readonly)
  Number of columns in the array.

• title : str
  Gets or sets the window title.

• cursor : str
  Gets or sets the mouse cursor shape. Setting to None hides the cursor.
  See avaliable cursor names in https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/cursors.html

• margin : int
  Gets or sets the board margin (px).

• cell_spacing : int
  Gets or sets the space between cells (px).

• margin_color : str
  Gets or sets the margin color.

• cell_color : str
  Gets or sets cells color
  See available color names in http://www.science.smith.edu/dftwiki/index.php/Color_Charts_for_TKinter

• grid_color : str
  Gets or sets grid color

• cell_size : int | (int, int)
  Gets or sets the cells dimension (width, height)

• on_key_press : function(key: str)
  Gets or sets the keyboard callback function

• on_mouse_click : function(button: str, row: int, col: int)
  Gets or sets the mouse callback function

• on_timer : function()
  Gets or sets the timer callback function

Methods

• show()
  Create the GUI, display and enter the run loop.

• clear()
  Clear the board, setting all values to None.

• close()
  Close the board, exiting the program.

• shuffle()
  Random shuffle all values in the board

• fill(value, row=None, col=None)
  Fill the board (or a row, or a column) with a value

  • value – The value to store
  • row (int) – Index of row to fill. Default=None (all rows)
  • col (int) – Index of column to fill. Default=None (all columns)

• create_output(**kwargs)
  Create a output message bar.

  • kwargs:
    • color = str
    • background_color = str
    • font_size = int

• print(*objects, sep=' ', end='')
  Print message to output bar.
  Use like built-in print() function.

• start_timer(msecs)
  Start a periodic timer that executes the a function every msecs milliseconds
  The callback function must be registered using .on_timer property.

  • msecs (int) – Time in milliseconds.

• stop_timer()
  Stops the current timer.

• pause(msecs, change_cursor=True)
  Delay the program execution for a given number of milliseconds.
  Warning: long pause freezes the GUI!

  • msecs (int) – Time in milliseconds.
  • change_cursor (bool) – Change the cursor to “watch” during pause?

TO DO

To do.... ;-)

How to Contribute

Submitting an issue

Use the issue tracker to submit bug reports and features or enhancements requests.

Translating

You can contribute by translating this document into other languages ​​(except en and pt_br).

Submitting a pull request

If you can improve anything in this project, feel free to add a pull request.

License

game2dboard is under MIT license. It can be reused within proprietary software provided that all copies of the licensed software include a copy of the MIT License terms and the copyright notice.