@database "MTLayoutEditor.guide"
@author "Geoffrey Whaite"
@remark "$VER: MTLayoutEditor Guide 1.0 (09.04.2000)
@remark "Created with GoldED 4.7.3 (23.6.97)"
@wordwrap
@index INDEX

@node MAIN "Mahjongg Tiles Layout Editor"

MTLayoutEditor - Layout Editor for MahjonggTiles

    @{" Introduction " link INTRODUCTION}
    @{" Requirements " link REQUIREMENTS}
    @{" Installation " link INSTALLATION}


Using MTLayoutEditor

    @{" Running MTLayoutEditor " link RUNNING}
    @{" Layout File Operations " link FILEOPS}
    @{" The MTLayoutEditor Main Window " link MAINWINDOW}
    @{" The Help Window " link HELPWINDOW}
    @{" Editing Layouts " link EDITING}
        @{" Selecting the Current Layer " link SELECTLAYER}
        @{" Basic Editing " link BASICEDITING}
        @{" Shifting Tiles " link SHIFTINGTILES}
        @{" Layer Clipboard Operations " link LAYERCLIP}
        @{" Undoing and Redoing " link UNDOREDO}
        @{" Editing Layout Properties " link LAYOUTPROPS}


Configuring MTLayoutEditor

    @{" The Settings Window " link SETTINGSWIN}
        @{" The Pens Settings Page " link PENPAGE}
        @{" The Guide Layers Settings Page " link GUIDELAYERPAGE}
        @{" The Edit Keys Settings Page " link EDITKEYPAGE}
        @{" The Undo Settings Page " link UNDOPAGE}


@endnode

@node INDEX "Index"

INDEX

@endnode

@node INTRODUCTION "Introduction to the MTLayoutEditor"

@{u}Introduction@{uu}

MTLayoutEditor is a companion program for MahjonggTiles that is used to create and edit MahjonggTiles game layouts. With MTLayoutEditor you can set the Name of a layout, the Comment for a layout, the layout metrics (width and height of the layout grid and the number of layers in the layout), the number of tiles in a layout and the placement of the tiles in the layout.

Features of MTLayoutEditor :-

 * Simple, easy to use.
 * Two independant guide layers to help with aligning layers.
 * Layer clipboard with Cut, Copy, Paste, Exchange and Replace.
 * Shift all the tiles on a layer (or the entire layout).
 * Undo/redo.
 * Help window available at any time by pressing the 'Help' key.
 * Highly configurable including :-
   - display colours.
   - editing command keys.
   - undo buffer size.
   - guide layer setup.


See also

@{" Requirements " link REQUIREMENTS}, @{" Installation " link INSTALLATION}

@endnode

@node REQUIREMENTS "Requirements for MTLayoutEditor"

@{u}Requirements@{uu}

No special requirements beyond those required by MahjonggTiles. See the MahjonggTiles documentation for details.

@endnode

@node INSTALLATION "Installing MTLayoutEditor"

@{u}Installation@{uu}

MTLayoutEditor is installed along with MahjonggTiles, no special installation is required.

@endnode

@node RUNNING "Using MTLayoutEditor"

@{u}Running MTLayoutEditor@{uu}

MTLayoutEditor can be launched by double clicking its icon or it can be launched with a CLI command. When run from a CLI an optional parameter specifying the initial layout file to edit can be included.

When launched from its icon or from the CLI without the layout parameter a 'Layout Select Window' is displayed for the user to select an existing layout to edit. If you wish to create a new layout rather than editing an existing layout then the 'Layout Select Window' should be cancelled instead of selecting a layout. If no initial layout is selected then a 'Layout Info Window' is opened to allow the user to specify the properties of a new layout to create.

MTLayoutEditor can also be launched from within MahjonggTiles by choosing the 'Run Layout Editor' menu item in the game's 'Layout' menu. When MTLayoutEditor is launched this way the current layout being played is loaded as the initial layout to edit.


See also

@{" The MTLayoutEditor Main Window " link MAINWINDOW}, @{" Layout File Operations " link FILEOPS}, @{" Editing Layouts " link EDITING}

@endnode

@node FILEOPS "Using MTLayoutEditor"

@{u}Layout File Operations@{uu}

Layout file operations allow the user to load an existing layout for editing, create a new layout, save a layout back to disk and save a layout to a new layout file. These operations are performed by choosing the appropriate menu items from the 'Layout' menu. These menu items are as follows :-

@{b}New Layout@{ub} - opens the 'Layout Info Window' to set the initial properties for a new layout. The new layout is created with no tiles placed.

@{b}Load Layout@{ub} - opens the 'Select Layout Window' to choose an existing layout to edit.

@{b}Save Layout@{ub} - saves the layout being edited to the current layout file. If this is a new layout that has not been previously saved then there is no currnt layout file and choosing this menu item is the same as choosing the 'Save Layout As' menu item.

@{b}Save Layout As@{ub} - opens an asl file requester to select a new filename to save the current layout to. The file chosen here becomes the current layout file.


See also

@{" Editing Layout Properties " link LAYOUTPROPS}

@endnode

@node MAINWINDOW "Using MTLayoutEditor"

@{u}The MTLayoutEditor Main Window@{uu}

MTLayoutEditor's main window is divided into two parts. At the top of the window is a control/status bar and below this is the editing panel where the user interacts with the program to edit the tile positions.

At the left of the control/status bar is the layer cycle gadget which is used to select the current layer to edit in the edit panel. To the right of the layer cycle gadget are a number status indicators used to indicate the current status of the program and the layout being edited. These status indicators include :-
 * the number of tiles placed in the layout and the total number of tiles.
 * the co-ordinates of the drag tile when the mouse is in the edit panel.
 * layout modified flag.
 * undo/redo and clipboard data available flags.


The edit panel displays the current layer being edited. It shows the layout grid, the tiles placed on the current layer and (optionally) two guide layers that show the position of tiles on other layers.

The layout grid is displayed as a grid of dashed lines on the edit panel background. The width of the edit grid is half a tile width and the height of the grid is half a tile height, thus a tile will occupy a 2 x 2 grid square.

Tiles on the current layer are drawn as a border, a solid center and a gap between the border and the center.

The guide layer tiles are drawn as a border filled with diagonal lines. The two different guide layer have their diagonal lines drawn in the opposite directions. The guide layers are configured individually in the 'Settings Window'.

When the mouse pointer is within the edit panel a 'drag tile cursor' is displayed and follows the mouse movements. This drag tile has the same shape as tiles on the current layer but different colour.

The colours used to render the various edit panel elements are user settable in the 'Settings Window'.


See also

@{" The Pens Settings Page " link PENPAGE}, @{" The Guide Layers Settings Page " link GUIDELAYERPAGE}, @{" Editing Layouts " link EDITING}

@endnode

@node HELPWINDOW "Using MTLayoutEditor"

@{u}The Help Window@{uu}

Pressing the 'Help' key will open the 'Help Window'. This window has a number of pages that give brief descriptions of the editor operations.

@endnode

@node EDITING "Editing Layouts"

@{u}Editing Layouts@{uu}

Editing layouts involves setting the layout properties (name, comment, size and number of tiles) and placing of the tiles within the layout.

The layout properties are set in the 'Layout Info Window', see @{" Editing Layout Properties " link LAYOUTPROPS} for details.

Several edit operations can be used to place tiles within the layout including @{" basic place and pick up of tiles " link BASICEDITING}, @{" shifting tiles in the layout " link SHIFTINGTILES} and @{" clipboard operations " link LAYERCLIP}.


See also

@{" Selecting The Current Layer " link SELECTLAYER}, @{" Undoing and Redoing " link UNDOREDO}, @{" The Help Window " link HELPWINDOW}

@endnode

@node SELECTLAYER "Editing Layouts"

@{u}Selecting the Current Layer@{uu}

Most editing operations performed with MTLayoutEditor apply to the current layer only so it is necessary to select the correct layer before performing the operation. Layers are numbered from zero, for the bottom layer, to N-1 for the top layer where N is the number of layers in the layout.

The layer cycle gadget at the left of the control/status bar (top of the main window) shows the current layer and can be used to select which layer is current. The current layer can also be selected using keys on the numeric keypad. The '+' key will change the current layer to the next higher layer (if we are not already at the top layer), the '-' key will change the current layer to the next lower layer (if we are not already at the bottom layer). The numeric keys ('0' to '9') will change directly to the correspondingly numbered layer. Thus pressing '0' on the numeric key pad will change to the bottom layer of the layout, pressing '1' will change to layer number 1 (the second from the bottom) and so on.

@endnode

@node BASICEDITING "Editing Layouts"

@{u}Basic Editing@{uu}

The basic editing functions of MTLayoutEditor are placing tiles in the layout and picking tiles up from the layout. These actions are performed in the edit panel of the main MTLayoutEditor window. Note that tiles can be picked up from or placed on the current layer only.

When the mouse is moved within the edit panel a 'drag tile' is displayed on the layout grid below the mouse pointer and follows the mouse as it is moved within the edit panel. This 'drag tile' has the same shape as tiles on the current layer but is displayed in a different colour. When the drag tile is moved directly over a tile already placed on the current layer it is displayed in a highlight colour to indicate that the tile at this location can be picked up. When a tile cannont be placed, either because all tiles have been placed in the layout or because it is partially obstructed by a tile already placed on the layer, then it is displayed ghosted (semi-transparent).

Tiles are placed or picked up at the 'drag tile' location by clicking the left mouse button. If there is no tile obstructing the 'drag tile' and there are still tiles unplaced in the layout then clicking the left mouse button will place a tile at that location on the current level. When the 'drag tile' is directly above an already placed tile (highlighted) then clicking the left mouse button will pick that tile up from the layout.

As tiles are placed and picked up the tiles placed status displayed is updated to reflect the new number of tiles placed in the layout.


See also

@{" The MTLayoutEditor Main Window " link MAINWINDOW}, @{" Selecting the Current Layer " link SELECTLAYER}, @{" Shifting Tiles " link SHIFTINGTILES}, @{" Layer Clipboard Operations " link LAYERCLIP}, @{" Undoing and Redoing " link UNDOREDO}

@endnode

@node SHIFTINGTILES "Editing Layouts"

@{u}Shifting Tiles@{uu}

All the tiles on the current layer can be shifted left, right, up or down by pressing the corresponding cursor key. Each time a cursor key is pressed the tiles are shifted one grid position in the direction of the cursor key pressed.

Normally tiles can be shifted to the edge of the layout but not beyond. Attempting to shift the tiles beyond the edge has no affect. This behaviour can be overridden by holding down the Control key while pressing the cursor key. When this happens any tile that is moved beyond the edge of the layout are removed from the layout and the tiles placed status display is updated to reflect the number of tiles remaining in the layout.

If either Shift key is pressed when the cursor key is pressed then the shift applies to all the tiles on all the layers of the layout rather than just the current layer. Both the Shift and Control keys may be pressed at the same time, this will shift all the tiles in the layout allowing tiles to be shifted off the layout.


See also

@{" The MTLayoutEditor Main Window " link MAINWINDOW}, @{" Selecting the Current Layer " link SELECTLAYER}, @{" Basic Editing " link BASICEDITING}, @{" Layer Clipboard Operations " link LAYERCLIP}, @{" Undoing and Redoing " link UNDOREDO}

@endnode

@node LAYERCLIP "Editing Layouts"

@{u}Layer Clipboard Operations@{uu}

MTLayoutEditor maintains a clipboard that can hold the locations of all the tiles on a layer. This clipboard is private to MTLayoutEditor and cannot be shared with other applications.

The following operations can be performed on the layer clipboard :-

@{b}Copy@{ub} - copies the location of all the tiles on the current layer to the clipboard.

@{b}Cut@{ub} - same as copy but also removes the tiles from the current layer.

@{b}Paste@{ub} - places tiles into the current layer at the locations given in the clipboard, if there is a collision between tiles already on the layer and tiles specified in the clipboard then the clipboard tile is not placed on the layer.

@{b}Force Paste@{ub} - places tiles into the current layer at the locations given in the clipboard, if there is a collision between tiles already on the layer and tiles specified in the clipboard then the tile currently on the layer is removed before the clipboard tile is placed.

@{b}Replace@{ub} - all the tiles on the current layer are removed and replaced by those tiles specified in the clipboard.

@{b}Exchange@{ub} - tiles already on the current layer are replaced with the tiles in the clipboard and the clipboard contents are replaced with the tiles that were already on the current layer.


These operations can be performed by choosing the appropriate item from the 'Edit' menu or by pressing the corresponding command key. The command keys can be set by the user in the 'Settings Window' and their current assignments are displayed on the right side of the menu item.

When there are tiles in the layer clipboard the 'CLIP' status indicator is shown. The contents of the clipboard may be freed by choosing the 'Free Clipboard' menu item in the 'Edit' menu.


See also

@{" The MTLayoutEditor Main Window " link MAINWINDOW}, @{" Selecting the Current Layer " link SELECTLAYER}, @{" Basic Editing " link BASICEDITING}, @{" Shifting Tiles " link SHIFTINGTILES}, @{" Undoing and Redoing " link UNDOREDO}, @{" The Edit Keys Settings Page " link EDITKEYPAGE}

@endnode

@node UNDOREDO "Editing Layouts"

@{u}Undoing and Redoing@{uu}

Whenever an editor operation is performed that changes the layout the operation is placed in an undo buffer so that the operation can be undone. Operations that can be undone are placeing and picking up tiles, shift operations, clipboard operation that change tiles on the current layer and editing layout properties.

When an operation is undone it can be redone again so long as no other editor operation has been performed since the undo. Whenever an editor operation is performed that placed undo data in the undo buffer any existing redo data in the undo buffer is lost.

The Undo and Redo operations are performed by choosing the 'Undo' or 'Redo' menu items in the 'Edit' menu or by pressing the corresponding command key. The command keys can be set by the user in the 'Settings Window' and their current assignments are displayed on the right side of the menu item.

The number of operations that can be saved in the undo buffer is user adjustable in the 'Settings Window'. Setting the undo buffer size to zero disables undo. There is also an option in the 'Settings Window' that allows the undo data to be kept when the layout is saved, normally saving a layout clears the undo buffer.

When there is undo data available in the undo buffer the 'UNDO' status indicator is displayed. When there is redo data available in the undo buffer the 'REDO' status indicator is displayed. The undo buffer can be cleared at any time by choosing the 'Clear Undo Buffer' menu item in the 'Edit' menu.


See also

@{" The MTLayoutEditor Main Window " link MAINWINDOW}, @{" Selecting the Current Layer " link SELECTLAYER}, @{" Basic Editing " link BASICEDITING}, @{" Shifting Tiles " link SHIFTINGTILES}, @{" Layer Clipboard Operations " link LAYERCLIP}, @{" The Edit Keys Settings Page " link EDITKEYPAGE}, @{" The Undo Settings Page " link UNDOPAGE}

@endnode

@node LAYOUTPROPS "Editing Layouts"

@{u}Editing Layout Properties@{uu}

Layout properties can be edited in the 'Layout Info Window'. This window is accessed by choosing the 'Layout Info' menu item in the 'Layout' menu. It is also displayed when a new layout is created to set the initial properties for the new layout. The properties editable in this window are as follows :-

@{b}Name@{ub} - the name of the layout. This is the name displayed in the 'Select Layout Window' list and, from within MahjongTiles, in the 'About MahjonggTiles Window'.

@{b}Comment@{ub} - a comment about the layout. This can be anything but will probably credit the creator of the layout. This comment is displayed in MahjonggTiles' 'About MahjonggTiles Window'.

@{b}Width@{ub} - the width of the layout in layout grid cells. Each layout grid cell is half as wide as the tile width.

@{b}Height@{ub} - the height of the layout in layout grid cell. Each layout grid cell is half as high as the tile height.

@{b}Number of Layers@{ub} - the number of layers in the layout. Layers are numbered from zero for the bottom cell to one less than the number of layers for the top layer.

@{b}Tile Quartets@{ub} - the number of tile quartets in the layout. There are four times as many tiles in the layout as there are tile quartets so the number of tiles in the layout is always a multiple of four. The number of tiles status display always shows four times the number set by this slider.


If any of the layout metrics (width, height or number of layers) of an existing layout are reduced then it is possible that some tiles already placed in the layout will no longer be wholly within the layout. When this occurs those tiles are removed from the layout.

@endnode

@node SETTINGSWIN "Configuring MTLayoutEditor"

@{u}The Settings Window@{uu}

MTLayoutEditor can be configured using the 'Settings Window' which is accessed by choosing the 'Editor Settings' menu item in the 'Settings' menu.

The 'Settings Window' is organized as a number of pages of related settings. These pages are :-

@{" Pens " link PENPAGE} - selects the colours to use to render the various components of the editor with.

@{" Guide Layers " link GUIDELAYERPAGE} - setup the guide layers.

@{" Edit Keys " link EDITKEYPAGE} - setup the command keys for operations in the edit menu.

@{" Undo " link UNDOPAGE} - setup undo options.


At the bottom of the 'Settings Window' is a button bank that allows the user to accept the changes made to the settings ('Ok') or to abandon the changes ('Cancel'). Both buttons close the 'Settings Window'.

There is no need to save the settings, this is performed automatically.

@endnode

@node PENPAGE "Configuring MTLayoutEditor"

@{u}The Pens Settings Page@{uu}

This page of the 'Settings Window' allows the user to choose the colours used to render the various elements of the Main Window's edit panel. The elements that can be setup this way are as follows :-

@{b}Background@{ub} - the background colour of the edit panel.

@{b}Grid@{ub} - the colour that the layout grid is rendered with.

@{b}This Layer Tiles@{ub} - the colour that tiles placed on this layer are rendered with.

@{b}Guide Layer #1@{ub} - the colour that the first guide layer is rendered with.

@{b}Guide Layer #2@{ub} - the colour that the second guide layer is rendered with.

@{b}Drag Tile@{ub} - the colour that the 'Drag Tile Cursor' is rendered with.

@{b}Drag Highlight@{ub} - the colour that the 'Drag Tile Cursor' is rendered with when it is placed above a tile that can be picked up.


See also

@{" The Settings Window " link SETTINGSWIN}

@endnode

@node GUIDELAYERPAGE "Configuring MTLayoutEditor"

@{u}The Guide Layers Settings Page@{uu}

This page of the 'Settings Window' allows the user to setup the two independant guide layers. The guide layers are used to show the positions of tiles on some layer or layers other than the current layer to assist in aligning tiles with other layers. The tiles on these guide layer are drawn with a diagonal pattern rather than the solid tiles on the current layer. The guide layer can be draw either behind or in front of the tiles on the current layer.

The contents of this page are two sub-pages, one for each guide layer. Each of these sub-pages has two gadgets for setting up the guide layer. The first is a cycle gadget that selects which other layers to include in the guide layer and the second is a checkbox to select whether the guide layer should be overlayed on top of the current layer or not.


See also

@{" The Settings Window " link SETTINGSWIN}

@endnode

@node EDITKEYPAGE "Configuring MTLayoutEditor"

@{u}The Edit Keys Settings Page@{uu}

This page of the 'Settings Window' allows the user to specify the command key shortcuts to use to perform the edit functions in the 'Edit' menu. The current key assigned to each 'Edit' menu item is displayed at the right of the menu item.

The edit functions that can have a command key assigned for them are the layer clipboard operations and the Undo and Redo operations.


See also

@{" The Settings Window " link SETTINGSWIN}, @{" Layer Clipboard Operations " link LAYERCLIP}, @{" Undoing and Redoing " link UNDOREDO}

@endnode

@node UNDOPAGE "Configuring MTLayoutEditor"

@{u}The Undo Settings Page@{uu}

This page of the 'Settings Window' allows the user to setup options for the Undo and Redo operations.

There are two gadgets in this page :-

@{b}Edit Buffer Size@{ub} - this slider sets the number of editor operations that can be stored in the undo buffer. Setting a high value set here allows more mistakes to be corrected but at the expense of greater memory usage. Setting the undo buffer size to zero disables undo.

@{b}Keep Undo on Save@{ub} - this checkbox selects whether the undo buffer should be retained or not when the layout is saved. Checking this checkbox will cause MTLayoutEditor to keep the undo data when a layout is saved, otherwise the undo data is discarded when the layout is saved.


See also

@{" The Settings Window " link SETTINGSWIN}, @{" Undoing and Redoing " link UNDOREDO}

@endnode