# DX1Layout

## This is Beta Software. Only cursory testing has been done. Use at your own risk.

Having said that, this program doesn't do anything fancy. It reads some text files and some image files and outputs one image file and saves prefs in a text file.

Obviously, if you stumble on a bug that has you stuck then please let me know right away. I'll try to help you work around it, or I'll try to fix it. mighty@mightydrake.com

Download DX1Layout

### Documentation:

This program eases the chore of documenting how an Ergodex DX1 or CH Products Multi Function Panel keyboard is laid out for various games. In the original DX1 software, they expected you to put the labels beside the buttons, so that the labels are visible when printed on paper and the sheet of paper is placed under the clear plastic of the keyboard. I don't use mine that way. I bring up my keyboard layout image on my second monitor so that I can refer to it while I'm playing without having to crane my neck to see the keyboard.

You will create or download a background image and create blanks for the buttons. Then, you'll build up a few .txt files that will tell the program where the keys are located on the DX1 surface, and how to label them. Click the Go! button and in a fraction of a second it'll spit out the image file.

The error checking is not particularly robust. So, if you feed the program really bad files then I wouldn't be too surprised if you manage to crash it. Nothing bad should happen. Hopefully, there's enough info in the output log to help you track down the problem. Then you can fix it and just try again.

Someday, I may put more of that information in the GUI, but this was quicker to program.

### Installation:

Requires .Net 4.0, which should already be installed on any Win7 or later machine. I believe it should work on 32-bit or 64-bit, though I've only tested it on Win7-64. I think it should work as a desktop app in Win8, but I haven't tested it. If anyone tries it I'd love to hear how it behaves for you.

No installation necessary for this program. Just copy the program into a folder. The only file from the .zip necessary for it to operate is DX1Layout.exe. The rest of the files in the .zip are example files and images used by this ReadMe file.

The program will default to looking for all of the files in the same directory as the program. So, it's most convenient to keep all of the .txt and image files you're using in that same directory.

### How to Use:

There are four .txt files used to lay out a keyboard. The Layout file, the Button file, the Game file, and the Labels file. The Layout file describes the actual layout of keys on the DX1. The Button file describes the button images that will be placed on the background, and the label areas on those buttons. The Game file has the name of the background, and says which Button file to use, and which Labels file to use, and the output filename. And the Labels file is the list of key names and actions applied to each button.

All files are assumed to be in the same directory.

Layout file - DX1Layout.txt: This file will probably be the same for every game, since you probably won't move any keys from one game to the next. This file is simply a collection of x, y, and rotation values.

The easiest way to create the Layout file is to place your buttons where you like them on your DX1. Then, put a blank, white piece of paper under the plastic. Then, take a picture straight down onto the keyboard from at least three or four feet. Crop that image to the actual keyboard area. Resize it to the final size that you want. Load it up into Paint.NET, or something similar, and use the mouse cursor to find the upper-left corner of each button. You can estimate the rotation. Get your buttons set up, or use my example buttons if they're the correct size. Then run the program the first time using your photograph as the Background file, with a blank Labels file, and it will place blank buttons based on your Layout file. If some of your placements are a little off, then you can edit the Layout file, save your work, and click the Go button, again.

I would recommend resizing the background file to a fairly large size. That gives you some flexibility in text size and placement on the buttons. You can resize it for viewing after running the program. I chose 1400x1050 for the background and 105x105 for the buttons in my examples because that fits well on my second monitor without any scaling. (If your buttons are the wrong size on your background, or if the buttons are not showing up at all, then check that the DPI matches. See below.*)

If you are using fewer than the maximum 50 buttons then just stop when you've gotten to the last one.

If you are missing any button numbers in the middle, then set that button to the same values as the one *after* it. For example, if you're missing button 10, then take the location of button 11 and put that on line 10 and line 11 of the file. That way, button 11 will overwrite button 10, and it's like it's not even there.

Obviously, keeping track of which button you're working on is a lot easier if you use a text editor that will show you the line numbers. I use Notepad++, but there are many alternatives.

Game file - DX1GameFile.txt: This file will only have four lines in it. The name of the Background image, the name of the Button file, the name of the Labels file, and the name of the Output image. Supported types for the images are: JPG, BMP, PNG, TIF, GIF. You can mix and match as is convenient. Meaning, you can have some JPG and some PNG, etc. The program treats them all separate. For the Output image, the program will look at the extension and choose the type of file to write based on that.

For your background image, you'll want it to be the same size that you used when you mapped out the positions of the buttons from the photograph. You can either start with a fancy background image, and place the buttons on that. Or, you can start with a blank image of that size, and then place logos or other art on it after the buttons are in place. Or, just keep the blank background.

Button file - DX1ButtonFile.txt: Like the Layout file, the Button file will probably be identical for all games, for most people. You'll create one set of blanks and use them for all of your games. On the other hand, if you're the creative type, then you can customize the buttons for some of your games. If you create rounded edges for your buttons then you're going to want to save them as PNG or GIF files, to make the corners of the image file transparent.

There will be four button images which are written on. A blank, a button with the game Action, an Other button (maybe larger label area), and a blank that will hold an icon. This file tells us the filenames of those button images, and will tell us where to put the text that will go onto those images. If you're not using some of the blanks, for example, the icon blank, then just set it to the same as the Blank button. The program is expecting this file to have four lines using this format.

For each of the four lines in the file, we'll have the name of the button image file. Then, for each of the three text fields available to put on the button we'll have font, size, color, horizontal alignment, vertical alignment, and location. The three text fields are in this order: DX1 button number, keyboard key, and game action.

Font is the name of the font. Example: Times New Roman

The size can be a decimal number. Example: 8.5

The color is in the form #rrggbb, like web colors. Example: #0000ff for blue.

The alignment fields have six possible values: L, R, C, T, B, X. These stand for: Left, Right, Center, Top, Bottom, Don't Draw. Obviously, L and R are for horizontal alignment and T and B are for vertical alignment. An example of using the X to skip a field would be the Blank button. For the Blank button you probably want to show only the button number, but not draw anything for the keyboard key nor the game action. Put an X in either alignment field for those pieces of information.

The location is a rectangle in the form: Left, Top, Width, Height.

Labels file - DX1Labels.txt: Each line of the Labels file will have the DX1 button number, the key name, which button blank to use, and then either the game action, or the name if the icon image to place on the button.

The DX1 button numbers do not have to be in order. This way, you can group common functions and easily copy them from one file to the next. If there are duplicates, then the first one will be used and the rest will be ignored.

The text in the label will automagically word-wrap. Or, you can force a line break by putting a \n in the text.

For any DX1 buttons which are in the Layout file but which do not appear in the Labels file, the program will use the blank button and place those buttons as specified in the Layout file.

To choose which button blank to use, the choices are B, A, O, I, for Blank, Action, Other, Icon.

The Icon button gives you the opportunity to place an icon onto a button, like an up arrow for forward, etc. If you want transparency, then be sure to save your file as a PNG or GIF, with the appropriate transparency info set. On the other hand, if you wanted, you could create basically a blank Icon button the same size as the regular buttons, and then use the "icon file" as a custom button. You could customize every button, if you wanted. That would be a lot of work, and kind of defeats the purpose of this program, but you can do that if you want :-)

Some things to note in the example DX1Labels.txt file that I included:

- The buttons are not in numerical order. I put a few out of order, to test how it worked. I left them there to illustrate.
- The first button in the file demonstrates the use of \n to force a line break.
- The second button demonstrates the use of the Icon button type.
- I have one example of the Other button type, which in my case is just a larger label area.
- I also have an example of an unknown button type, which produces a red error message in the output. The program is able to ignore that type of error and continue with the rest of the layout.

### Running the Program:

It's pretty straightforward. If you start the program in the same folder as all of your source files, then you can leave the Base Directory to the default. You can type in the names of the Layout and Game .txt files. Or, you can use the browse buttons to locate them. It will remember these from one run to the next.

When you're ready, click the Go! button.

The program will spit out some information about its progress. If there are no errors then you can ignore it. It should finish in less than a second.

Look in your folder and you should see the output image file. Look at it and see if you like it.

Repeated runs will pop up a warning about overwriting the output file. If you only run it two or three times, that's no big deal. But, if you're going through a lot of attempts then the Overwrite checkbox will disable that warning. That's especially useful when you're first tweaking your Layout file. That will probably take several iterations.

### Final Thoughts:

If you're an artist, and you've worked with programmers on a user interface, then you probably understand the term Programmer Art. It's often UGLY. The example files I've included are not particularly pretty. They're merely functional. I'd love it if some people who use this program would send me some of their button files, and some of the output files they've produced. Let me know if you want to give me permission to include them with future versions of the program, or display them on my website. I'll assume that they're only for me, unless told specifically otherwise. mighty@mightydrake.com

It just occurred to me that you can use a PNG file as a background that is blank and entirely transparent. After you run the program to place the buttons, you'll have an image that you can load into most paint programs that will honor the transparency. That way, you can load the buttons onto an image of any size and visually slide them around until they look good. That might produce a more pleasing image than drawing the buttons directly onto a fixed-size background. (In my experience, when I try to load the buttons onto an image that's designed as a desktop wallpaper, the buttons end up obscuring significant details of the background.)

### * DPI Issue

Make sure that the DPI of your background file and your button files match. My camera defaulted to 72 dpi and my paint program defaulted to 96 dpi. The first time I ran the program the buttons on the background were too small. And then later, I downloaded an image from the web for use as a background. The DPI of that file was set to 4, and my buttons showed up just as little marks on the image. It took me over half an hour to figure out why it worked with the old background but not the new one. I recommend Irfanview for simple changes like this. Go into the Image | Information screen to make the changes. Click the Change button and remember to Save the file.

Eaxmples of buttons which are the wrong size. Click the images to see the full size images

Background at 72 DPI - Buttons at 96 DPI | Background at 4 DPI - Buttons at 96 DPI

### Change Log:

v0.90 04/MAY/13

- Iniitial release

v0.91 16/FEB/14:

- Added version number
- Changed .NET requirement to v4.0 Client
- A few tweaks to the documentation

### Someday/Maybe:

These are notes to myself of things I'm considering doing in the future, to make the program a little more user-friendly. But, since I've already got it all set up, I'm inclined to just use it as-is. If I get a couple of people asking for one or two of these features then I might be able to do them. If you have ideas for other changes then go ahead and ask, and I'll see if I can set aside time to do that.

Once again, if you stumble on a bug that has you stuck then please let me know right away. I'll try to help you work around it, or I'll try to fix it. mighty@mightydrake.com

Popup warning for mismatched DPI
Better yet, set the DPI without altering image size
Create output name based on input image name
Checkbox
.jpg in Game File
If output name already exists, offer to add a number to the end. Ex. Output1.jpg, Output2.jpg, etc.
Radio buttons: Warn, Sequential, Overwrite
Checkmark or button to automagically open image
Put some sort of file type identifier in the text files, or come up with extensions to use. This gives extra error checking, and could give them a way to choose the file besides a file browser
Show green/red icon when files are found?
Replace Game file and Button file with UI controls. Use those files to load those controls
Save settings based on image filename?
Add What Game is This at the top
Give some thought to how to organize input and output files better. Less manual work to go through a bunch of input images for a new game
Maybe do some sort of multi-select, to save off a batch of input images. Look at date-time of first and find everything within an hour of that
Allow some way to select a subset to run the program against
Display buttons and put example text in place, and let them tweak font, etc
First line of Layout file is the size of the background expected? Resize to fit that? ex. 1600,1200,-1 (-1 is a Magic Number, so I know you read the documentation)
Obviously, it would be nice to have assistance in creating the Layout file. An outline that you can drag around and rotate and then record the info
Allow for more text decorations, like rotation, italic, bold, drop shadow, underline
Allow for any number of button blanks. Put the identifier character on that line. Maybe allow names instead of just single characters
Allow for varying number of label fields. For example, the blank will only have one
Identify what's being written for each field. This would allow for the button number in more than one place.
Allow Labels file to set the color. This way, movement buttons can be one color and weapons can be a different color. This can also be handled with different button blanks
Change Button file to a more flexible format, like maybe xml
Change Labels file to a more flexible format. We'll need this if we make the buttons fancier
Provide a button or an option to view the output image file
Comment lines
If I group the buttons in the Labels file, it might be convenient to describe their location on the layout Ex. Pinkie buttons, Movement buttons, Weapons row
Draw numbers down the left side with lines to the buttons (mine got scattered all over the keyboard, so sometimes they're hard to find without help) (Ended up doing this by hand)
Add a button to PolygonalHell DX1 Utility to spit out buttons defined and the key assigned. That can be the beginning of a Labels File (Done on my copy. Available upon request)

Files included:
DX1Layout.exe
DX1LayoutReadme.html
DX1LayoutScreenshot.jpg
DX1Layout.txt
DX1Button.txt
DX1GameFile.txt
DX1Labels.txt
DX1ButtonFileScreenCap.jpg
DX1Background.jpg
DX1PhotoBackground.jpg
DX1BlankBackground.jpg
DX1SaintsRowBackground.jpg
DX1SaintsRowOutput.jpg
DX1Blank.png
DX1Action.png
DX1Other.png
DX1Icon.png
DX1DownArrowIcon.png