GUI Features

This file is intended as a brief summary of the options that may be used while in the PythonTk empire interface.

Note: The Tk interface is designed to appear differently depending on which platform it is currently running on. This document expects the user to be somewhat versed in the standard GUI policies of their platform.


The Map Window:

The map window displays text character representations for each sector that has been parsed by a dump or map command. If the sector has a newdesignation that differs from the current designation then the map will display two characters - the current designation followed by the newdesignation. Otherwise, only the current designation is shown. In addition to the standard text characters, a hexagon will be displayed around known land sectors. These hexagons will be colored green for owned sectors, red for enemy sectors, black for deity sectors, and grey for unknown sectors. (These are the default colors; they may be changed in the TkOption file.)

In addition to the sector representations, land/ship/plane units will be displayed on the map as well. By default, a small blue square will be displayed in sectors that contain ships, a pink square designates planes, and a brown represents land units.

Along with providing information on sector designations and unit locations, there are a number of mouse events that the map window will recognize:

Additionally, the size of the main graphical map window may be resized by clicking and dragging the small box located in the lower right corner of the map window. (Additional map windows opened via the Map command can be resized using the window manager.)


Command-line Window:

The command line is an integral part of this client. All keystrokes go directly to the command line. The graphical portions of the client are intended merely as an adjunct (never a replacement) for the standard text interface. On platforms that support clipboards (such as the X selection under X-Windows) select, copy, and insert text should work normally.

There are a couple of key sequences that will produce specific results: When tab is pressed, the identifier of the object that is being viewed in the censor window is inserted into the current command-line. When Alt and one of the characters "gyujnb" is pressed, the key will be inserted into the command line and the censor window's selection will be moved. The movement is in accordance with the standard empire usage of these keys.

Otherwise, the command-line functions similarly to other clients - commands get typed in, and output gets sent back.

When viewing output on the command-console, the censor window can be instructed to view a sector by pressing the right mouse button over a text description of a sector (text of the form "x,y").


Censor Window:

The censor window is located in the upper left hand corner of the main window. The censor window can be changed to view sectors, ships, land units, or planes. In a nutshell, the censor window displays the output from the dump command in a more digestible form. (Although admittedly, it is still pretty ugly at this stage.)

For unit censors, a listbox will be positioned underneath the censor window. This may be used to select which units to display. There are three methods of selecting sectors in the censor window:

Some of the censor window entries have special left mouse button bindings associated with them. For example, you may set commodity thresholds, or deliver thresholds by left clicking on their respective boxes. In general, if the border around the field value changes when the mouse is moved over it, then that value can be set. Most of these bindings are fairly straight forward - they issue server commands that reset the quantity. A more advanced case, however, is the use of the sector commodity quantity field. When clicking on this field, a server command will be issued that moves commodities to/from the sector's dist center.


Graphical move utility:

Pressing a mouse button over the quantity field of a commodity in the sector census window will cause the main map window to be placed in a move mode.

Using this mode, the selected commodity can be moved by pointing and clicking source and destination sectors. Also, arbitrary sectors may be selected as mobility way-points.

When move mode is first enabled the default path will be between the sector selected in the census window and its dist path. If the sector does not have a dist sector than a source sector will need to be manually selected.

Enabling move mode will cause the quantity box in the area below the map window to receive the input focus. (Clicking on the command-line will return the input focus.) By default, commodities will be moved to or from the source sector such that the specifed quantity will remain in the destination sector. That is, the amount specifies a commodity level not the amount to be moved. See the Mover command for information on flags than can alter the meaning of the amount field.

When the map is in move mode it rebinds the actions of the right mouse button according to the following rules:


Status Line:

At the bottom of the root window is a status line.

The status line contains four fields.


Queue Options Menu:

The Queue Options menu can be opened by pressing a mouse button over the queue status button, which is located in the status window. (The bottom most part of the main window.) The Queue Options menu can be used to alter the state of the outgoing queue. There are currently four options on the menu: In addition to the above queue options, the Tk interface implements a special "tear off" option - by pressing the mouse over the small dashed-line within this menu, the menu will become a root window which may remain displayed while performing other options. To delete this window, use the window managers close function.


Login Window:

The login window allows host/port and country/representative information to be entered graphically. Normally this window will only appear when a server is being connected for the first time. To start a connection, enter the server's host and port information in their respective fields. Then enter your country and representative information in their respective fields.

The login window can also be forced open via the Login command. If a server or country is changed using this command, the database will probably have inaccurate information from the old country. It is recommended that "Reset Database" be selected each time a new country is connected to. (Note: The best way to handle multiple countries is to specify a database file on the command line, or to load a new database file dynamically via the load/save buttons.)

The login window is separated into three sections:

Database Section
The active database may be changed within the client as long the client is not currently connected to a server. Only one server may be active at any given time. (To connect to two servers simultaneously, run the client twice.) The database section supports the following buttons:
Server Information
This section provides input boxes for server information. This information is used when determining which empire server to connect to. Values in this section may only be changed when off-line.
Player Information
This section stores information on the country used to connect to the previously specified empire server. There are two input boxes, a kill checkbox, and a Play Button in this section:

The close window function of your window manager can be used to dismiss the Login window. However, the Login Window will automatically close when a server is successful connection occurs.


Additional Output Windows:

Extra server output windows may be opened at any time. Any empire server command that is prefaced by "wind " will open an output window and redirect the command's output to that window. These additional output windows work independent of empire server input-output. It is possible to leave these windows open while issuing and receiving additional commands.

These output windows have a scrollbar attached to them, and they support selection of the censor window by pressing the right mouse button over a text description of a sector.

Use the window manager's close window function to close an output window.


The Telegram Tool Window:

The telegram window may be opened by sending the command wread at the command-line. The telegram window supports viewing, sending, and replying to telegrams and announcements.

The low-level parsers will automatically grab both incoming and outgoing telegrams and update this display. If there is a shortage of disk space, it may be necessary to use the Delete button to remove unwanted telegrams from the database.

A sector may be "extracted" from a telegram by pressing the right-mouse button over a text description of the sector. The client will scan the area surrounding the mouse cursor for text of the form " x,y ". If the scan produces a sector, then it is automatically selected by the censor window.

The telegram window can be thought of as containing three sections:

Limiting Messages
Because a significant amount of telegrams or announcements can be accumulated during the course of a game, it is often helpful to be able to limit the listing to only contain relevant messages. The top part of the telegram window supports this message limiting feature.
The Messages
The messages in the listing window are sorted in reverse-received order (most recent messages are at the top of the list). The time displayed next to each telegram is a local time approximation of the telegram's reported server time. Every message selected is displayed in the message window. If more than one message is selected than more than one message will be displayed simultaneously in the message window.
Message Actions
The bottom portion of the telegram window supports actions that may be performed on the listing of telegrams.

Use the close window function of your window manager to close the telegram window.


Configuring the Client:

There is a standard text file in the distribution called "TkOption". It contains a number of Tk configuration commands. Using this mechanism, it is possible to alter the client's color and font scheme. Personalized coloring schemes for all of the windows and objects may be specified here. On some platforms it may be necessary to edit this file to change the default font from a proportional font to a fixed font.

In addition to the standard TkOption file, some platforms will load an additional platform specific initialization file. On Unix systems the file TkOption.x11 will be loaded after TkOption. On Windows based machines the file TkOption.w32 will be loaded. Options in these files will take precedence over options in the main TkOption file.

Please see these files for examples on how to configure the Tk Widgets.


Exiting the Client:

Use the window manager's close command to exit the client.