Events¶

PubMarine is used to pass events from the UI to the Dispatcher. These are the events that are emitted over the course of the program. Events normally report information about changes but we also use it as a general bus between the frontend and backend to pass commands and return data as well. This allows the frontend and backend to operate asynchronously in some cases, decouples the precise APIs from each other, and allows us to pass a single PubPen object around to handle communication instead of having to pass references to each object whose methods we wanted to invoke.

User events¶

User events return information about user objects.

user.cash.update(new_cash: int, old_cash: int)¶

Emitted when a change occurs in the amount of a user’s cash on hand

Parameters:	new_cash (int) – The amount of cash a user now has old_cash – The amount of cash the user had before

user.login_success(username: string)¶

Emitted when a user logs in successfully.

Parameters:	username (string) – The username that successfully logged in

user.login_failure(msg: string)¶

Emitted when a login attempt fails

Parameters:	msg (string) – A message explaining why the attempt failed

user.info(username: string, cash: int, location: string)¶

Emitted in response to a query.user.info(). This comtains all relevant information about a user.

Parameters:	username (string) – The user who the information is about cash (int) – The amount of cash the user has on their person location (string) – The location that the user is in currently

user.order_failure(msg: string)¶

Emitted when an order attempt fails

Parameters:	msg (string) – A message explaining why the attempt failed

Ship Events¶

Ship events return information about ship objects.

ship.cargo.update(amount_left: ManifestEntry, free_space: int, filled_hold: int)¶

Emitted when a ship’s cargo manifest changes (commodities are bought and sold or transferred to a warehouse)

Parameters:	amount_left (ManifestEntry) – A `magnate.ship.ManifestEntry` that shows how much of a commodity is left on board. free_space (int) – Amount of the hold that’s free filled_hold (int) – Amount of the hold that’s filled

ship.destinations(destinations: list)¶

Emitted when the destinations a ship can travel to changes. This usually means that the ship has moved to a new location which has different options.

Parameters:	destinations (list) – A list of strings showing where the ship can travel from here.

ship.equip.update(holdspace: int)¶

Emitted when a ship’s equipment changes

Parameters:	cargo_space – The total cargo space in the ship currently has

ship.info(ship_type: string, free_space: int, filled_space: int, manifest: dict of ManifestEntry)¶

Emitted in response to a query.ship.info(). This contains all relevant information about a ship.

Parameters:	ship_type (string) – The type of ship free_space (int) – How much hold space is available filled_space (int) – How much hold space is used manifest (dict) – The commodities that are in the hold. This is a dictionary of ManifestEntry types

ship.moved(new_location: string, old_location: string)¶

Emitted when a ship changes location.

Parameters:	new_location (string) – The location that the ship moved to old_location (string) – The location that the ship moved from

ship.movement_failure(msg: string)¶

Emitted when a ship attempted to move but failed.

Parameters:	msg (string) – A message explaining why the movement failed

Market Events¶

Market events carry information about a specific market to the client.

market.event(location, commodity, price, msg: string)¶

Emitted when an event occurs at a market. This is for informational purposes. The client may choose to display the message for game flavour. Once markets become stateful, this may become more useful.

Parameters:	msg (string) – A message about the market

market.{location}.info(prices: dict)

Emitted in response to a query.market.{location}.info(). This carries information about prices of all commodities in a market.

Parameters:	prices (dict) – A mapping of commodity name to its current price

market.{location}.purchased(commodity: string, quantity: int)

This contains information when a user successfully purchases a commodity at a specific market.

Parameters:	commodity (string) – The name of the commodity that was bought quantity (int) – The amount of the commodity that was purchased

market.{location}.sold(commodity: string, quantity: int)

This contains information when a user successfully sold a commodity at a specific market.

Parameters:	commodity (string) – The name of the commodity that was sold quantity (int) – The amount of the commodity that was sold

market.{location}.update(commodity: string, price: int)

Emitted when the price of a commodity changes.

Parameters:	commodity (string) – The name of the commodity being operated upon price (string) – The new price of the commodity

Action Events¶

Action events signal the dispatcher to perform an action on behalf of the user.

action.ship.movement_attempt(destination: string)¶

Emitted when the user requests that the ship be moved. This can trigger a ship.moved() or ship.movement_failure() event.

Parameters:	destination (string) – The location to attempt to move the ship to

action.user.login_attempt(username: string, password: string)¶

Emitted when the user submits credentials to login. This can trigger a user.login_success() or user.login_failure() event.

Parameters:	username (string) – The name of the user attempting to login password (string) – The password for the user

action.user.order(order: magnate.ui.event_api.Order)¶

Emitted when the user requests that a commodity be bought from a market. Triggers one of market.{location}.purchased(), market.{location}.sold(), or user.order_failure().

Parameters:	order (magnate.ui.event_api.Order) – All the details necessary to buy or sell this commodity.

Query Events¶

These events are requests from the frontend for information from the backend. This could simply be to get information during initialization or it could be to resynchronize a cache of the values if it’s noticed that something is off.

query.cargo.info()¶: Emitted to retrieve a complete record of the cargoes that are being carried in a ship. This triggers a ship.cargo() event.

query.market.{location}.info(): Emitted to retrieve a complete record of commodities to buy and sell at a location.

query.user.info(username: string)¶

Emitted to retrieve a complete record of the user from the backend.

Parameters:	username (string) – The user about whom to retrieve information

query.warehouse.{location}.info(): Emitted to retrieve a complete record of the cargoes being held in a location’s warehouse.

UI Events¶

UI events are created by a single user interface plugin for internal communication. For instance, a menu might want to communicate that a new window needs to be opened and populated with data. All UI events should be namespaced under ui.[PLUGINNAME] so as not to conflict with other plugins.

Urwid Interface¶

These are UI Events used by the Urwid interface. Urwid has its own event system but using it requires that the widget that wants to observe the event must have a reference to the widget that emits it. When dealing with a deep hierarchy of widgets it can be painful to pass these references around so the Urwid interface makes use of our pubmarine event dispatcher for some things.

ui.urwid.message(msg: string, severity=MsgType.info: magnate.ui.urwid.message_win.MsgType)¶

Emitted to have the message window display a new message.

Parameters:	msg – The message to display to the user severity – Optional value that tells whether the message is merely informational or informs the error of some error. The message_win will display more severe messages with special highlighting.

ui.urwid.order_info(commodity: string, price: int)¶

Emitted to inform the transaction dialog what commodity and price the user is interested in.

Parameters:	commodity (string) – Name of the commodity to buy or sell price (int) – Price of the commodity