# 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. Even if you don't have a second monitor, you can print out the layout and keep it handy for reference during a game.

To use this program, you will 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. You can use that image file as-is to see the buttons. Or, you can create or download game-related images from the ‘Net and paste this button layout image, with transparency, onto the background. I use Paint.NET to do that, but there are many alternatives. With Paint.NET, I can quickly and easily move, resize, and stretch the buttons to make them look as good as possible on the background image.

The error checking in this program 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 previews into the GUI. But this was quicker to program.

### Installation:

Requires .Net 4.0, which should already be installed on any Win 7 or later machine.

I believe it should work on 32-bit or 64-bit, though I've only tested it on Win 7 x64 and Win 10 x64. It should also work in Win 8.x, but I haven't tested it. If anyone tries it I'd love to hear how it behaves for you.

This is a portable program. No installation necessary. Just copy the program into a folder. I recommend somewhere under the Documents folder, because the user account has write permissions for that 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. You can override that for each individual file, if you wish.

### How to Use:

There are three .txt files used to lay out a keyboard. The Layout file, the Button file, and the Game file.

The Layout file describes the physical layout of keys on the DX1.

The Button file specifies the button images that will be placed on the background, and the defines the label areas on those buttons.

The Game file is the list of key names and actions applied to each button.

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 program produces a 1400 x 1000 pixel image, so the x and y values will be within an area that size.

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.

Load that image up into Paint.NET, or something similar. Crop the image to the actual keyboard area. Resize it to 1400 x 1000 pixels.

Then use the mouse cursor to find the upper-left corner of each button. Paint.NET displays the current pixel location in the status bar at the bottom of the image. You can estimate the rotation, in degrees.

Then, create a blank GameFile.txt. Use the default DX1ButtonFile.txt, along with the default DX1ButtonBlank.png button image. Run the program. It will place blank buttons based on your Layout file. Now, use your image editor to paste the output GameFile.png, with transparency, onto your photo of the DX1 keyboard. 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.

Photograph of DX1 | Output from program | Overlay output onto photograph to check alignment
Example of creating the key layout from a photograph

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.

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.

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.

On the 1400 x 1000 field of the output file, the buttons should be 100 pixels high and wide. You can use larger button images if you want, but they won’t match up with the physical keyboard. 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 must be at least one button in the Button file. The first button will be used as a “blank” button, for any button not specifically labeled in the Game file.

The maximum number of button styles is 50. This might be useful for people who use different buttons for different games, but want to keep all of their button definitions in one file.

For each button style in the file, we'll have several pieces of information. The name of the button image file. Then, three fields to describe the look of the text information that we put on the button: DX1 button number, keyboard key, and game action. The information needed for each of the three text fields are font name, font size, font color, horizontal alignment, vertical alignment, and location on the button.

The font name is the actual Windows 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 DX1 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.

Game file - DX1 GameFile.txt: In addition to describing the labels on the buttons, the Game file is also the name used for the output file. For example, DX1GameFile.txt will produce output file DX1GameFile.png.

Each line of the Game file will have the DX1 button number, the key name, which button style 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 Game file, the program will treat the first button in the Button file as the blank button and place those buttons as specified in the Layout file.

To choose which button to draw onto, just use the appropriate line number in the Button file.

To put an icon onto the button like an up arrow for forward, etc. put an “i” prior to the button number. Example, “i4” (without quotes.) In that case, the Action field will be where the icon is placed onto the button. And, the action field of the button in the Game file will be the name of the icon file. If you want transparency in your icon, 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, with the action field the same size as the button, and then use the "icon file" as a complete 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 :-)

Examples:

1,PrtSc,2,Multi Line\nLabel | DX1 button #1, PrtSc key, button style line 2, with a multi-line label with a line break
2,S,I4,DX1IconArrowDown.png | DX1 button #2, “S” key, button style line 4 holding an icon, icon file name
3,A,2,Left | DX1 button #3, “A” key, button style line 2, text “Left”

Some things to note in the example DX1GameFile.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 four buttons demonstrate the use of the Icon button type.

- The next button in the file demonstrates the use of \n to force a line break.

- 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, Button 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 red error messages then you can ignore that output. It should finish in less than a second.

The output image name will be the same name as your GameFile.txt except it’ll have a .png extension. 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. I'll assume that they're only for me, unless told specifically otherwise. 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. mighty@mightydrake.com

For the Button file, I put a max of 50 on there, even though most games will only need two or three button styles. By allowing this many button styles, one thing you can do is use different colors for different groups of buttons. Movement buttons might use one color text, or a button image with particular highlights. Weapon buttons might be colored differently, etc. Also, with this many buttons allowed, you might be able to store different button styles for multiple games in this one Button file. Albeit, they’ll all use the first button as the blank button, for buttons with no corresponding label.

### Pasting Button Image onto background with transparency in Paint.NET

Whenever I bought a new game, I'd have to re-learn this. So, I figured I’d save some people the hassle of having to look it up. And, by typing this, it’s more likely that I’ll remember next time.

1. Go search the Internet for files you like. As long as it’s for your own personal use, and you’re not redistributing the file, it’s legal. I usually grab a whole bunch of wallpapers and similar images related to the current game. I paste the buttons onto all of them. When playing that game, it gives me a variety of choices for which to display, based on my current whim.

2. Open the background file in Paint.NET. You can do that with File | Open, or by just dropping the image onto Paint.NET

3. Choose Layers | Import From File… and select the .png button output file.

4. You can drag the buttons around by clicking almost anywhere within the selected region, except the dot in the very center. You can resize by grabbing the corners.

5. When you have it as you like it, choose File | Save As… and choose an output type and name. I usually save to JPG. Paint.NET has to flatten the file. I find I don’t really need to save the .pdn. I’m not going to be coming back to this to edit it. If I ever want to change it, it’s quick enough to start from scratch.

### 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

v1.0 09/JAN/17

- Completely threw out writing the output directly onto a background downloaded from the Internet. Now, the output file is just the buttons on a transparent background, saved as a png. Use Paint.NET or some other image editing program to interactively scale and place the buttons onto the background.

- Layout and Button files stayed the same. Discarded old Game file. Changed the name of the Labels file to Game file.

- Allow for an arbitrary number of button styles, max 50.

- Output file is the name of the Game file with a .png extension.

- Show filename in overwrite dialog

- Sidesteps output numbering issue.

- Sidesteps the DPI issue.

### 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

When changing UI fields, log needs to reflect the change
Example: Change Game File field, Log still shows filename from startup
Version numbers in prefs, button, and game files. Maybe layout, too
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?
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
Display buttons and put example text in place, and let them tweak font, etc
Allow for more text decorations, like rotation, italic, bold, drop shadow, underline
Allow for varying number of label fields. For example, the blank will only have one
Colors on the buttons, to help group them
Color outlines
Colored blocks Identify what's being written for each field. This would allow for the button number in more than one place.
Change Button file to a more flexible format, like maybe xml
Change Game file to a more flexible format. We'll need this if we make the buttons fancier
Comment lines
If I group the buttons in the Game 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 (Forked. Discussion. Releases on Github.) to spit out buttons defined and the key assigned. That can be the beginning of a Game File (Done on my copy. Available upon request)

I might just revamp this completely. Display the buttons on the background in real time. Move and scale the buttons. Scale the image. Act as a naming tool. But, since changing to the paste-into-Paint.NET process, I’m less inclined to do this.

It would be nice to preview and edit the button text layout in real time, though.

Files included:
DX1Layout.exe
DX1LayoutReadme.html
DX1LayoutScreenshot.png
DX1Layout.txt
DX1ButtonFile.txt
DX1GameFile.txt
DX1GameFileBlank.txt
DX1MightysKeyboardPhoto.jpg
DX1GameFileBlank.png
DX1MightysKeyboardPhotoOverlay.jpg
DX1SaintsRowBackground.jpg
DX1Gamefile.png
DX1SaintsRowBackgroundOverlayed.jpg
DX1ButtonBlank.png
DX1Button2Line.png
DX1Button4Line.png
DX1ButtonIcon.png
DX1IconArrowDown.png
DX1IconArrowLeft.png
DX1IconArrowRight.png
DX1IconArrowUp.png
DX1ButtonFileScreenCap.png

Copyright © 2013-2017 All Rights Reserved Drake Christensen